--- title: Beta url: https://platform.claude.com/docs/en/api/php/beta --- # Beta ## Domain types ### Anthropic Beta - `class AnthropicBeta` - `string` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `"telemetry-destinations-2026-08-11"` - `"webhooks-2026-10-07"` - `"message-threads-2026-08-12"` - `"analytics-usage-cost-2026-08-24"` - `"experimental-claude-tag-2026-10-21"` ### Beta API Error - `class BetaAPIError` - `"api_error" type` - `string message` ### Beta Authentication Error - `class BetaAuthenticationError` - `"authentication_error" type` - `string message` ### Beta Billing Error - `class BetaBillingError` - `"billing_error" type` - `string message` ### Beta Currency - `enum BetaCurrency` ### Beta Error - `class BetaError` - `class BetaInvalidRequestError` - `"invalid_request_error" type` - `string message` - `class BetaAuthenticationError` - `"authentication_error" type` - `string message` - `class BetaBillingError` - `"billing_error" type` - `string message` - `class BetaPermissionError` - `"permission_error" type` - `string message` - `class BetaNotFoundError` - `"not_found_error" type` - `string message` - `class BetaRateLimitError` - `"rate_limit_error" type` - `string message` - `class BetaGatewayTimeoutError` - `"timeout_error" type` - `string message` - `class BetaAPIError` - `"api_error" type` - `string message` - `class BetaOverloadedError` - `"overloaded_error" type` - `string message` ### Beta Error Response - `class BetaErrorResponse` - `"error" type` - `BetaError error` - `?string requestID` ### Beta Gateway Timeout Error - `class BetaGatewayTimeoutError` - `"timeout_error" type` - `string message` ### Beta Invalid Request Error - `class BetaInvalidRequestError` - `"invalid_request_error" type` - `string message` ### Beta Monetary Amount - `class BetaMonetaryAmount` - `string amount` 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. - `BetaCurrency currency` 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 - `class BetaNotFoundError` - `"not_found_error" type` - `string message` ### Beta Overloaded Error - `class BetaOverloadedError` - `"overloaded_error" type` - `string message` ### Beta Permission Error - `class BetaPermissionError` - `"permission_error" type` - `string message` ### Beta Rate Limit Error - `class BetaRateLimitError` - `"rate_limit_error" type` - `string message` ## Beta › Models ### List Models `$client->beta->models->list(?string afterID, ?string beforeID, ?list lifecycle, ?int limit, ?list betas, ?string workspaceID): Page` **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 - `afterID?: 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. - `beforeID?: 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 list` (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. - `limit?: optional int` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. default: 20 - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaModelInfo` - `"model" type` Object type. For Models, this is always `"model"`. - `string id` Unique model identifier. - `?list allowedFallbackModels` Model IDs this model accepts as `fallbacks[i].model` on the Messages API. An empty list means the `fallbacks` parameter is not supported for this model as primary. - `?BetaModelCapabilities capabilities` Object mapping capability names to their support details. Keys are always present for all known capabilities. - `\Datetime createdAt` RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. - `?\Datetime deprecatedAt` 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`. - `string displayName` A human-readable name for the model. - `Lifecycle lifecycle` 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. - `?BetaModelLine line` 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`. - `?int maxInputTokens` Maximum input context window size in tokens for this model. - `?int maxTokens` Maximum value for the `max_tokens` parameter when using this model. - `?\Datetime retiresAt` 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. #### Example ```php beta->models->list( afterID: 'after_id', beforeID: 'before_id', lifecycle: ['active'], limit: 1, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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": "opus", "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 `$client->beta->models->retrieve(string modelID, ?list betas, ?string workspaceID): BetaModelInfo` **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 - `modelID: string` (path parameter) Model identifier or alias. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaModelInfo` - `"model" type` Object type. For Models, this is always `"model"`. - `string id` Unique model identifier. - `?list allowedFallbackModels` Model IDs this model accepts as `fallbacks[i].model` on the Messages API. An empty list means the `fallbacks` parameter is not supported for this model as primary. - `?BetaModelCapabilities capabilities` Object mapping capability names to their support details. Keys are always present for all known capabilities. - `\Datetime createdAt` RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. - `?\Datetime deprecatedAt` 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`. - `string displayName` A human-readable name for the model. - `Lifecycle lifecycle` 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. - `?BetaModelLine line` 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`. - `?int maxInputTokens` Maximum input context window size in tokens for this model. - `?int maxTokens` Maximum value for the `max_tokens` parameter when using this model. - `?\Datetime retiresAt` 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. #### Example ```php beta->models->retrieve( 'model_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaModelInfo); ``` ##### 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": "opus", "max_input_tokens": 0, "max_tokens": 0, "retires_at": "2019-12-27T18:11:19.117Z", "type": "model" } ``` ## Beta › Messages ### Create a Message `$client->beta->messages->create(int maxTokens, list messages, Model model, ?BetaCacheControlEphemeral cacheControl, ?BetaCompactionConfig compaction, ?Container container, ?BetaContextManagementConfig contextManagement, ?BetaDiagnosticsParam diagnostics, ?FallbackCreditToken fallbackCreditToken, ?BetaFallbacksParam fallbacks, ?string inferenceGeo, ?list mcpServers, ?BetaMetadata metadata, ?BetaOutputConfig outputConfig, ?BetaJSONOutputFormat outputFormat, ?ServiceTier serviceTier, ?Speed speed, ?list stopSequences, ?System system, ?BetaThinkingConfigParam thinking, ?BetaMessageThreadParam thread, ?BetaToolChoice toolChoice, ?list tools, ?list betas, ?string userProfileID, ?string workspaceID): BetaMessage` **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=php) #### Parameters - `maxTokens: int` 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=php#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=php) for details. - `messages: list` 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=php#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=php). 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=php#give-claude-a-role), you can use the top-level `system` parameter. There is a limit of 100,000 messages in a single request. - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `cacheControl?: optional BetaCacheControlEphemeral` Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. - `compaction?: optional BetaCompactionConfig` 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 Container` Container identifier for reuse across requests. - `contextManagement?: optional BetaContextManagementConfig` 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 BetaDiagnosticsParam` 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. - `fallbackCreditToken?: optional FallbackCreditToken` The `fallback_credit_token` from a prior refusal's `stop_details`. When a preceding request was refused and returned a `fallback_credit_token`, pass that code here on the retry to have the retry's cache-creation tokens for the prefix that was warm on the refused model billed at the cache-read rate. Must be redeemed by the same organization and workspace, with the same request body (optionally extended by one appended `assistant` message whose content is the partial text — with any trailing whitespace stripped from the final text block — and paired server-tool blocks streamed before the refusal; the appended-assistant form is not available for requests with `output_format` set or forced `tool_choice`), on an eligible fallback model, on the same platform, and within 5 minutes of the refusal; a mismatch is a 400. A token minted mid-server-tool-loop whose partial content was continuable may only be redeemed with the appended-assistant form — if an exact-body retry is rejected with a 400 saying the token must be redeemed by continuing the partial response, retry with the appended-assistant form instead. When the appended-assistant form is used on a model that otherwise disallows assistant-turn prefill, this token also authorizes that one prefill. - `fallbacks?: optional BetaFallbacksParam` 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=php#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. - `inferenceGeo?: optional string` Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used. - `mcpServers?: optional list` MCP servers to be utilized in this request - `metadata?: optional BetaMetadata` An object describing metadata about the request. - `outputConfig?: optional BetaOutputConfig` Configuration options for the model's output, such as the output format. - `serviceTier?: optional ServiceTier` Determines whether to use priority capacity (if available) or standard capacity for this request. Anthropic offers different levels of service for your API requests. See [service-tiers](https://platform.claude.com/docs/en/api/service-tiers?sdk_languages=php) for details. - `speed?: optional Speed` 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=php) for which models. - `stopSequences?: optional list` 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 System` System prompt. A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices?sdk_languages=php#give-claude-a-role). - `thinking?: optional BetaThinkingConfigParam` 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=php#configuring-thinking) for each model's behavior. - `thread?: optional BetaMessageThreadParam` Server-held conversation state (a Thread). `{"type": "create"}` asks the server to hold this conversation's state under the response's `id`; `{"type": "continue", "previous_message_id": ...}` resumes from a previous response so only the new turn's messages are sent. The response shape is unchanged. - `toolChoice?: optional BetaToolChoice` 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. - `tools?: optional list` 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=php), 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=php)). 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=php) for more details. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `userProfileID?: 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. - `workspaceID?: 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. - `outputFormat?: optional BetaJSONOutputFormat` **Deprecated** Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs?sdk_languages=php) A schema to specify Claude's output format in responses. This parameter will be removed in a future release. #### Returns - `class BetaMessage` - `"message" type` Object type. For Messages, this is always `"message"`. - `string id` Unique object identifier. The format and length of IDs may change over time. - `?BetaContainer container` Information about the container used in this request. This will be non-null if a container tool (e.g. code execution) was used. - `list content` Content generated by the model. This is an array of content blocks, each of which has a `type` that determines its shape. Example: ```json [{"type": "text", "text": "Hi, I'm Claude."}] ``` If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. For example, if the input `messages` were: ```json [ {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, {"role": "assistant", "content": "The best answer is ("} ] ``` Then the response `content` might be: ```json [{"type": "text", "text": "B)"}] ``` - `?BetaContextManagementResponse contextManagement` Context management response. Information about context management strategies applied during the request. - `?BetaDiagnostics diagnostics` Request-level diagnostics. `null` when the request did not supply `diagnostics`, or when it did and no prompt-cache divergence was detected. - `Model model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"assistant" role` Conversational role of the generated message. This will always be `"assistant"`. - `?BetaRefusalStopDetails stopDetails` Structured information about why model output stopped. This is `null` when the `stop_reason` has no additional detail to report. - `?BetaStopReason stopReason` The reason that we stopped. This may be one the following values: * `"end_turn"`: the model reached a natural stopping point * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated * `"tool_use"`: the model invoked one or more tools * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. * `"refusal"`: when streaming classifiers intervene to handle potential policy violations * `"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. - `?string stopSequence` Which custom stop sequence was generated, if any. This value will be a non-null string if one of your custom stop sequences was generated. - `BetaUsage usage` Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - `?list inputTransformations` 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`. - `class BetaRawMessageStreamEvent` - `class BetaRawMessageStartEvent` - `"message_start" type` - `BetaMessage message` - `class BetaRawMessageDeltaEvent` - `"message_delta" type` - `?BetaContextManagementResponse contextManagement` Information about context management strategies applied during the request - `Delta delta` - `BetaMessageDeltaUsage usage` Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - `?list inputTransformations` 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`. - `class BetaRawMessageStopEvent` - `"message_stop" type` - `class BetaRawContentBlockStartEvent` - `"content_block_start" type` - `ContentBlock contentBlock` - `int index` - `class BetaRawContentBlockDeltaEvent` - `"content_block_delta" type` - `BetaRawContentBlockDelta delta` - `int index` - `class BetaRawContentBlockStopEvent` - `"content_block_stop" type` - `int index` #### Example ```php beta->messages->create( maxTokens: 1024, messages: [['content' => 'Hello, world', 'role' => 'user']], model: Model::CLAUDE_OPUS_5_5, cacheControl: ['type' => 'ephemeral', 'ttl' => '5m'], compaction: ['type' => 'summarize', 'instructions' => 'instructions'], container: [ 'id' => 'id', 'skills' => [ ['skillID' => 'pdf', 'type' => 'anthropic', 'version' => 'latest'] ], ], contextManagement: [ 'edits' => [ [ 'type' => 'clear_tool_uses_20250919', 'clearAtLeast' => ['type' => 'input_tokens', 'value' => 0], 'clearToolInputs' => true, 'excludeTools' => ['string'], 'keep' => ['type' => 'tool_uses', 'value' => 0], 'trigger' => ['type' => 'input_tokens', 'value' => 1], ], ], ], diagnostics: ['previousMessageID' => 'previous_message_id'], fallbackCreditToken: 'x', fallbacks: 'default', inferenceGeo: 'inference_geo', mcpServers: [ [ 'name' => 'name', 'type' => 'url', 'url' => 'url', 'authorizationToken' => 'authorization_token', 'toolConfiguration' => ['allowedTools' => ['string'], 'enabled' => true], ], ], metadata: ['userID' => '13803d75-b4b5-4c3e-b2a2-6f21399b021b'], outputConfig: [ 'effort' => 'low', 'format' => ['schema' => ['foo' => 'bar'], 'type' => 'json_schema'], 'taskBudget' => ['total' => 1024, 'type' => 'tokens', 'remaining' => 0], ], outputFormat: ['schema' => ['foo' => 'bar'], 'type' => 'json_schema'], serviceTier: 'auto', speed: 'standard', stopSequences: ['string'], system: [ [ 'text' => 'Today\'s date is 2024-06-01.', 'type' => 'text', 'cacheControl' => ['type' => 'ephemeral', 'ttl' => '5m'], 'citations' => [ [ 'citedText' => 'The grass is green. The sky is blue.', 'documentIndex' => 0, 'documentTitle' => 'x', 'endCharIndex' => 0, 'startCharIndex' => 0, 'type' => 'char_location', ], ], ], ], thinking: [ 'type' => 'adaptive', 'blockBinding' => [ 'prefixMismatchBehavior' => BetaThinkingPrefixMismatchBehavior::ERROR ], 'display' => 'summarized', ], thread: ['type' => 'create'], toolChoice: ['type' => 'auto', 'disableParallelToolUse' => true], tools: [ [ 'inputSchema' => [ 'type' => 'object', 'properties' => ['location' => 'bar', 'unit' => 'bar'], 'required' => ['location'], ], 'name' => 'name', 'allowedCallers' => ['direct'], 'cacheControl' => ['type' => 'ephemeral', 'ttl' => '5m'], 'deferLoading' => true, 'description' => 'Get the current weather in a given location', 'eagerInputStreaming' => true, 'inputExamples' => [['foo' => 'bar']], 'strict' => true, 'type' => 'custom', ], ], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], userProfileID: 'anthropic-user-profile-id', workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaMessage); ``` ##### 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 `$client->beta->messages->countTokens(list messages, Model model, ?BetaCacheControlEphemeral cacheControl, ?BetaCompactionConfig compaction, ?BetaContextManagementConfig contextManagement, ?list mcpServers, ?BetaOutputConfig outputConfig, ?BetaJSONOutputFormat outputFormat, ?Speed speed, ?System system, ?BetaThinkingConfigParam thinking, ?BetaToolChoice toolChoice, ?list tools, ?list betas, ?string userProfileID, ?string workspaceID): BetaMessageTokensCount` **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=php) #### Parameters - `messages: list` 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=php#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=php). 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=php#give-claude-a-role), you can use the top-level `system` parameter. There is a limit of 100,000 messages in a single request. - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `cacheControl?: optional BetaCacheControlEphemeral` Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. - `compaction?: optional BetaCompactionConfig` 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`. - `contextManagement?: optional BetaContextManagementConfig` Context management configuration. This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not. - `mcpServers?: optional list` MCP servers to be utilized in this request - `outputConfig?: optional BetaOutputConfig` Configuration options for the model's output, such as the output format. - `speed?: optional Speed` 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=php) for which models. - `system?: optional System` System prompt. A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices?sdk_languages=php#give-claude-a-role). - `thinking?: optional BetaThinkingConfigParam` 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=php#configuring-thinking) for each model's behavior. - `toolChoice?: optional BetaToolChoice` 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. - `tools?: optional list` 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=php), 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=php)). 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=php) for more details. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `userProfileID?: 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. - `workspaceID?: 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. - `outputFormat?: optional BetaJSONOutputFormat` **Deprecated** Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs?sdk_languages=php) A schema to specify Claude's output format in responses. This parameter will be removed in a future release. #### Returns - `class BetaMessageTokensCount` - `?BetaCountTokensContextManagementResponse contextManagement` Information about context management applied to the message. - `int inputTokens` The total number of tokens across the provided list of messages, system prompt, and tools. #### Example ```php beta->messages->countTokens( messages: [['content' => 'Hello, world', 'role' => 'user']], model: Model::CLAUDE_OPUS_5_5, cacheControl: ['type' => 'ephemeral', 'ttl' => '5m'], compaction: ['type' => 'summarize', 'instructions' => 'instructions'], contextManagement: [ 'edits' => [ [ 'type' => 'clear_tool_uses_20250919', 'clearAtLeast' => ['type' => 'input_tokens', 'value' => 0], 'clearToolInputs' => true, 'excludeTools' => ['string'], 'keep' => ['type' => 'tool_uses', 'value' => 0], 'trigger' => ['type' => 'input_tokens', 'value' => 1], ], ], ], mcpServers: [ [ 'name' => 'name', 'type' => 'url', 'url' => 'url', 'authorizationToken' => 'authorization_token', 'toolConfiguration' => ['allowedTools' => ['string'], 'enabled' => true], ], ], outputConfig: [ 'effort' => 'low', 'format' => ['schema' => ['foo' => 'bar'], 'type' => 'json_schema'], 'taskBudget' => ['total' => 1024, 'type' => 'tokens', 'remaining' => 0], ], outputFormat: ['schema' => ['foo' => 'bar'], 'type' => 'json_schema'], speed: 'standard', system: [ [ 'text' => 'Today\'s date is 2024-06-01.', 'type' => 'text', 'cacheControl' => ['type' => 'ephemeral', 'ttl' => '5m'], 'citations' => [ [ 'citedText' => 'The grass is green. The sky is blue.', 'documentIndex' => 0, 'documentTitle' => 'x', 'endCharIndex' => 0, 'startCharIndex' => 0, 'type' => 'char_location', ], ], ], ], thinking: [ 'type' => 'adaptive', 'blockBinding' => [ 'prefixMismatchBehavior' => BetaThinkingPrefixMismatchBehavior::ERROR ], 'display' => 'summarized', ], toolChoice: ['type' => 'auto', 'disableParallelToolUse' => true], tools: [ [ 'inputSchema' => [ 'type' => 'object', 'properties' => ['location' => 'bar', 'unit' => 'bar'], 'required' => ['location'], ], 'name' => 'name', 'allowedCallers' => ['direct'], 'cacheControl' => ['type' => 'ephemeral', 'ttl' => '5m'], 'deferLoading' => true, 'description' => 'Get the current weather in a given location', 'eagerInputStreaming' => true, 'inputExamples' => [['foo' => 'bar']], 'strict' => true, 'type' => 'custom', ], ], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], userProfileID: 'anthropic-user-profile-id', workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaMessageTokensCount); ``` ##### Response (200) ```json { "context_management": { "original_input_tokens": 0 }, "input_tokens": 2095 } ``` ## Beta › Messages › Batches ### Create a Message Batch `$client->beta->messages->batches->create(list requests, ?list betas, ?string userProfileID, ?string workspaceID): MessageBatch` **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=php) #### Parameters - `requests: list` List of requests for prompt completion. Each is an individual request to create a Message. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `userProfileID?: 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. Applies to every request in the batch; an individual request whose `user_profile_id` body field conflicts with this header is errored. - `workspaceID?: 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 - `class MessageBatch` - `"message_batch" type` Object type. For Message Batches, this is always `"message_batch"`. - `string id` Unique object identifier. The format and length of IDs may change over time. - `?\Datetime archivedAt` RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. - `?\Datetime cancelInitiatedAt` RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. - `\Datetime createdAt` RFC 3339 datetime string representing the time at which the Message Batch was created. - `?\Datetime endedAt` RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. - `\Datetime expiresAt` RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. - `ProcessingStatus processingStatus` Processing status of the Message Batch. - `MessageBatchRequestCounts requestCounts` Tallies requests within the Message Batch, categorized by their status. Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. - `?string resultsURL` URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. #### Example ```php beta->messages->batches->create( requests: [ [ 'customID' => 'my-custom-id-1', 'params' => [ 'maxTokens' => 1024, 'messages' => [['content' => 'Hello, world', 'role' => 'user']], 'model' => Model::CLAUDE_OPUS_5_5, 'cacheControl' => ['type' => 'ephemeral', 'ttl' => '5m'], 'compaction' => [ 'type' => 'summarize', 'instructions' => 'instructions' ], 'container' => [ 'id' => 'id', 'skills' => [ ['skillID' => 'pdf', 'type' => 'anthropic', 'version' => 'latest'] ], ], 'contextManagement' => [ 'edits' => [ [ 'type' => 'clear_tool_uses_20250919', 'clearAtLeast' => ['type' => 'input_tokens', 'value' => 0], 'clearToolInputs' => true, 'excludeTools' => ['string'], 'keep' => ['type' => 'tool_uses', 'value' => 0], 'trigger' => ['type' => 'input_tokens', 'value' => 1], ], ], ], 'diagnostics' => ['previousMessageID' => 'previous_message_id'], 'fallbackCreditToken' => 'x', 'fallbacks' => 'default', 'inferenceGeo' => 'inference_geo', 'mcpServers' => [ [ 'name' => 'name', 'type' => 'url', 'url' => 'url', 'authorizationToken' => 'authorization_token', 'toolConfiguration' => [ 'allowedTools' => ['string'], 'enabled' => true ], ], ], 'metadata' => ['userID' => '13803d75-b4b5-4c3e-b2a2-6f21399b021b'], 'outputConfig' => [ 'effort' => 'low', 'format' => ['schema' => ['foo' => 'bar'], 'type' => 'json_schema'], 'taskBudget' => [ 'total' => 1024, 'type' => 'tokens', 'remaining' => 0 ], ], 'outputFormat' => [ 'schema' => ['foo' => 'bar'], 'type' => 'json_schema' ], 'serviceTier' => 'auto', 'speed' => 'standard', 'stopSequences' => ['string'], 'stream' => false, 'system' => [ [ 'text' => 'Today\'s date is 2024-06-01.', 'type' => 'text', 'cacheControl' => ['type' => 'ephemeral', 'ttl' => '5m'], 'citations' => [ [ 'citedText' => 'The grass is green. The sky is blue.', 'documentIndex' => 0, 'documentTitle' => 'x', 'endCharIndex' => 0, 'startCharIndex' => 0, 'type' => 'char_location', ], ], ], ], 'thinking' => [ 'type' => 'adaptive', 'blockBinding' => [ 'prefixMismatchBehavior' => BetaThinkingPrefixMismatchBehavior::ERROR, ], 'display' => 'summarized', ], 'thread' => ['type' => 'create'], 'toolChoice' => ['type' => 'auto', 'disableParallelToolUse' => true], 'tools' => [ [ 'inputSchema' => [ 'type' => 'object', 'properties' => ['location' => 'bar', 'unit' => 'bar'], 'required' => ['location'], ], 'name' => 'name', 'allowedCallers' => ['direct'], 'cacheControl' => ['type' => 'ephemeral', 'ttl' => '5m'], 'deferLoading' => true, 'description' => 'Get the current weather in a given location', 'eagerInputStreaming' => true, 'inputExamples' => [['foo' => 'bar']], 'strict' => true, 'type' => 'custom', ], ], ], ], ], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], userProfileID: 'anthropic-user-profile-id', workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaMessageBatch); ``` ##### 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 `$client->beta->messages->batches->retrieve(string messageBatchID, ?list betas, ?string workspaceID): MessageBatch` **GET** `/v1/messages/batches/{message_batch_id}` This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the `results_url` field in the response. Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing?sdk_languages=php) #### Parameters - `messageBatchID: string` (path parameter) ID of the Message Batch. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class MessageBatch` - `"message_batch" type` Object type. For Message Batches, this is always `"message_batch"`. - `string id` Unique object identifier. The format and length of IDs may change over time. - `?\Datetime archivedAt` RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. - `?\Datetime cancelInitiatedAt` RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. - `\Datetime createdAt` RFC 3339 datetime string representing the time at which the Message Batch was created. - `?\Datetime endedAt` RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. - `\Datetime expiresAt` RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. - `ProcessingStatus processingStatus` Processing status of the Message Batch. - `MessageBatchRequestCounts requestCounts` Tallies requests within the Message Batch, categorized by their status. Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. - `?string resultsURL` URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. #### Example ```php beta->messages->batches->retrieve( 'message_batch_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaMessageBatch); ``` ##### 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 `$client->beta->messages->batches->list(?string afterID, ?string beforeID, ?int limit, ?list betas, ?string workspaceID): Page` **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=php) #### Parameters - `afterID?: 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. - `beforeID?: 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 int` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. default: 20 - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class MessageBatch` - `"message_batch" type` Object type. For Message Batches, this is always `"message_batch"`. - `string id` Unique object identifier. The format and length of IDs may change over time. - `?\Datetime archivedAt` RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. - `?\Datetime cancelInitiatedAt` RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. - `\Datetime createdAt` RFC 3339 datetime string representing the time at which the Message Batch was created. - `?\Datetime endedAt` RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. - `\Datetime expiresAt` RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. - `ProcessingStatus processingStatus` Processing status of the Message Batch. - `MessageBatchRequestCounts requestCounts` Tallies requests within the Message Batch, categorized by their status. Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. - `?string resultsURL` URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. #### Example ```php beta->messages->batches->list( afterID: 'after_id', beforeID: 'before_id', limit: 1, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->messages->batches->cancel(string messageBatchID, ?list betas, ?string workspaceID): MessageBatch` **POST** `/v1/messages/batches/{message_batch_id}/cancel` Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a `canceling` state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation. 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=php) #### Parameters - `messageBatchID: string` (path parameter) ID of the Message Batch. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class MessageBatch` - `"message_batch" type` Object type. For Message Batches, this is always `"message_batch"`. - `string id` Unique object identifier. The format and length of IDs may change over time. - `?\Datetime archivedAt` RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. - `?\Datetime cancelInitiatedAt` RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. - `\Datetime createdAt` RFC 3339 datetime string representing the time at which the Message Batch was created. - `?\Datetime endedAt` RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. - `\Datetime expiresAt` RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. - `ProcessingStatus processingStatus` Processing status of the Message Batch. - `MessageBatchRequestCounts requestCounts` Tallies requests within the Message Batch, categorized by their status. Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. - `?string resultsURL` URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. #### Example ```php beta->messages->batches->cancel( 'message_batch_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaMessageBatch); ``` ##### 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 `$client->beta->messages->batches->delete(string messageBatchID, ?list betas, ?string workspaceID): DeletedMessageBatch` **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=php) #### Parameters - `messageBatchID: string` (path parameter) ID of the Message Batch. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class DeletedMessageBatch` - `"message_batch_deleted" type` Deleted object type. For Message Batches, this is always `"message_batch_deleted"`. - `string id` ID of the Message Batch. #### Example ```php beta->messages->batches->delete( 'message_batch_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaDeletedMessageBatch); ``` ##### Response (200) ```json { "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF", "type": "message_batch_deleted" } ``` ### Retrieve Message Batch results `$client->beta->messages->batches->resultsStream(string messageBatchID, ?list betas, ?string workspaceID): BaseStream` **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=php) #### Parameters - `messageBatchID: string` (path parameter) ID of the Message Batch. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class MessageBatchIndividualResponse` - `string customID` Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. Must be unique for each request within the Message Batch. - `MessageBatchResult result` Processing result for this request. Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. #### Example ```php beta ->messages ->batches ->resultsStream( 'message_batch_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaMessageBatchIndividualResponse); ``` ## Beta › Agents ### Create Agent `$client->beta->agents->create(Model model, string name, ?string description, ?BetaManagedAgentsExecutionIdentityParams executionIdentity, ?list mcpServers, ?array metadata, ?BetaManagedAgentsMultiagentParams multiagent, ?list skills, ?string system, ?list tools, ?list betas, ?string workspaceID): BetaManagedAgentsAgent` **POST** `/v1/agents` Create Agent #### Parameters - `model: Model` Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview?sdk_languages=php#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. - `description?: optional string` Description of what the agent does. - `executionIdentity?: optional BetaManagedAgentsExecutionIdentityParams` Execution principal for runs of this agent. Omitting it, sending null, or sending `{"type": "service_account"}` stores the default. - `mcpServers?: optional list` 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=php). - `metadata?: optional array` Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `multiagent?: optional BetaManagedAgentsMultiagentParams` Multiagent orchestration configuration. - `skills?: optional list` Skills available to the agent. - `system?: optional string` System prompt for the agent. - `tools?: optional list` Tool configurations available to the agent. Maximum of 256 tools across all toolsets allowed. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsAgent` - `"agent" type` - `string id` - `?\Datetime archivedAt` When the agent was archived. Null if not archived. - `\Datetime createdAt` A timestamp in RFC 3339 format - `?string description` - `BetaManagedAgentsExecutionIdentity executionIdentity` Execution principal for runs of this agent. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `list mcpServers` - `array metadata` - `BetaManagedAgentsModelConfig model` Model identifier and configuration. - `?BetaManagedAgentsMultiagent multiagent` Multiagent orchestration configuration. Null when the agent is single-threaded. - `string name` - `list skills` - `?string system` - `list tools` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `int version` The agent's current version. Starts at 1 and increments when the agent is modified. #### Example ```php beta->agents->create( model: BetaManagedAgentsModel::CLAUDE_OPUS_5_5, name: 'My First Agent', description: 'A general-purpose starter agent.', executionIdentity: [ 'roleARN' => 'arn:aws:iam::228601553692:role/T', 'type' => 'aws_role' ], mcpServers: [ [ 'name' => 'example-mcp', 'type' => 'url', 'url' => 'https://example-server.modelcontextprotocol.io/sse', ], ], metadata: ['foo' => 'bar'], multiagent: [ 'agents' => ['agent_011CZkYqphY8vELVzwCUpqiQ', ['type' => 'self']], 'type' => 'coordinator', ], skills: [['skillID' => 'xlsx', 'type' => 'anthropic', 'version' => '1']], 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: [ [ 'type' => 'agent_toolset_20260401', 'configs' => [ [ 'name' => 'bash', 'enabled' => true, 'permissionPolicy' => ['type' => 'always_allow'], 'type' => 'bash', ], ], 'defaultConfig' => [ 'enabled' => true, 'permissionPolicy' => ['type' => 'always_allow'] ], ], ], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsAgent); ``` ##### 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 `$client->beta->agents->list(?\Datetime createdAtGte, ?\Datetime createdAtLte, ?bool includeArchived, ?int limit, ?string page, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/agents` List Agents #### Parameters - `createdAtGte?: optional \Datetime` (query parameter) Return agents created at or after this time (inclusive). - `createdAtLte?: optional \Datetime` (query parameter) Return agents created at or before this time (inclusive). - `includeArchived?: optional bool` (query parameter) Include archived agents in results. Defaults to false. - `limit?: optional int` (query parameter) Maximum results per page. Default 20, maximum 100. - `page?: optional string` (query parameter) Opaque pagination cursor from a previous response. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsAgent` - `"agent" type` - `string id` - `?\Datetime archivedAt` When the agent was archived. Null if not archived. - `\Datetime createdAt` A timestamp in RFC 3339 format - `?string description` - `BetaManagedAgentsExecutionIdentity executionIdentity` Execution principal for runs of this agent. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `list mcpServers` - `array metadata` - `BetaManagedAgentsModelConfig model` Model identifier and configuration. - `?BetaManagedAgentsMultiagent multiagent` Multiagent orchestration configuration. Null when the agent is single-threaded. - `string name` - `list skills` - `?string system` - `list tools` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `int version` The agent's current version. Starts at 1 and increments when the agent is modified. #### Example ```php beta->agents->list( createdAtGte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtLte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), includeArchived: true, limit: 0, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->agents->retrieve(string agentID, ?int version, ?list betas, ?string workspaceID): BetaManagedAgentsAgent` **GET** `/v1/agents/{agent_id}` Get Agent #### Parameters - `agentID: string` (path parameter) Unique identifier of the agent to retrieve. - `version?: optional int` (query parameter) Agent version. Omit for the most recent version. Must be at least 1 if specified. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsAgent` - `"agent" type` - `string id` - `?\Datetime archivedAt` When the agent was archived. Null if not archived. - `\Datetime createdAt` A timestamp in RFC 3339 format - `?string description` - `BetaManagedAgentsExecutionIdentity executionIdentity` Execution principal for runs of this agent. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `list mcpServers` - `array metadata` - `BetaManagedAgentsModelConfig model` Model identifier and configuration. - `?BetaManagedAgentsMultiagent multiagent` Multiagent orchestration configuration. Null when the agent is single-threaded. - `string name` - `list skills` - `?string system` - `list tools` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `int version` The agent's current version. Starts at 1 and increments when the agent is modified. #### Example ```php beta->agents->retrieve( 'agent_011CZkYpogX7uDKUyvBTophP', version: 0, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsAgent); ``` ##### 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 `$client->beta->agents->update(string agentID, ?string description, ?BetaManagedAgentsExecutionIdentityParams executionIdentity, ?list mcpServers, ?array metadata, ?Model model, ?BetaManagedAgentsMultiagentParams multiagent, ?string name, ?list skills, ?string system, ?list tools, ?int version, ?list betas, ?string workspaceID): BetaManagedAgentsAgent` **POST** `/v1/agents/{agent_id}` Update Agent #### Parameters - `agentID: string` (path parameter) Unique identifier of the agent to update. - `description?: optional string` Description. Omit to preserve; send empty string or null to clear. - `executionIdentity?: optional BetaManagedAgentsExecutionIdentityParams` Execution principal for runs of this agent. Full replacement. Omit to preserve; send null or `{"type": "service_account"}` to restore the default. - `mcpServers?: optional list` 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=php). - `metadata?: optional array` 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 Model` Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview?sdk_languages=php#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 BetaManagedAgentsMultiagentParams` 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. - `skills?: optional list` 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. - `tools?: optional list` 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 int` 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. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsAgent` - `"agent" type` - `string id` - `?\Datetime archivedAt` When the agent was archived. Null if not archived. - `\Datetime createdAt` A timestamp in RFC 3339 format - `?string description` - `BetaManagedAgentsExecutionIdentity executionIdentity` Execution principal for runs of this agent. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `list mcpServers` - `array metadata` - `BetaManagedAgentsModelConfig model` Model identifier and configuration. - `?BetaManagedAgentsMultiagent multiagent` Multiagent orchestration configuration. Null when the agent is single-threaded. - `string name` - `list skills` - `?string system` - `list tools` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `int version` The agent's current version. Starts at 1 and increments when the agent is modified. #### Example ```php beta->agents->update( 'agent_011CZkYpogX7uDKUyvBTophP', description: 'updated', executionIdentity: [ 'roleARN' => 'arn:aws:iam::228601553692:role/T', 'type' => 'aws_role' ], mcpServers: [ [ 'name' => 'example-mcp', 'type' => 'url', 'url' => 'https://example-server.modelcontextprotocol.io/sse', ], ], metadata: ['foo' => 'string'], model: [ 'id' => BetaManagedAgentsModel::CLAUDE_OPUS_5_5, 'effort' => 'low', 'inferenceGeo' => 'inference_geo', 'speed' => 'standard', ], multiagent: [ 'agents' => ['agent_011CZkYqphY8vELVzwCUpqiQ', ['type' => 'self']], 'type' => 'coordinator', ], name: 'name', skills: [['skillID' => 'xlsx', 'type' => 'anthropic', 'version' => '1']], 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: [ [ 'type' => 'agent_toolset_20260401', 'configs' => [ [ 'name' => 'bash', 'enabled' => true, 'permissionPolicy' => ['type' => 'always_allow'], 'type' => 'bash', ], ], 'defaultConfig' => [ 'enabled' => true, 'permissionPolicy' => ['type' => 'always_allow'] ], ], ], version: 1, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsAgent); ``` ##### 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 `$client->beta->agents->archive(string agentID, ?list betas, ?string workspaceID): BetaManagedAgentsAgent` **POST** `/v1/agents/{agent_id}/archive` Archive Agent #### Parameters - `agentID: string` (path parameter) Unique identifier of the agent to archive. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsAgent` - `"agent" type` - `string id` - `?\Datetime archivedAt` When the agent was archived. Null if not archived. - `\Datetime createdAt` A timestamp in RFC 3339 format - `?string description` - `BetaManagedAgentsExecutionIdentity executionIdentity` Execution principal for runs of this agent. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `list mcpServers` - `array metadata` - `BetaManagedAgentsModelConfig model` Model identifier and configuration. - `?BetaManagedAgentsMultiagent multiagent` Multiagent orchestration configuration. Null when the agent is single-threaded. - `string name` - `list skills` - `?string system` - `list tools` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `int version` The agent's current version. Starts at 1 and increments when the agent is modified. #### Example ```php beta->agents->archive( 'agent_011CZkYpogX7uDKUyvBTophP', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsAgent); ``` ##### 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 `$client->beta->agents->versions->list(string agentID, ?int limit, ?string page, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/agents/{agent_id}/versions` List Agent Versions #### Parameters - `agentID: string` (path parameter) Agent ID to list versions for. - `limit?: optional int` (query parameter) Maximum results per page. Default 20, maximum 100. - `page?: optional string` (query parameter) Opaque pagination cursor. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsAgent` - `"agent" type` - `string id` - `?\Datetime archivedAt` When the agent was archived. Null if not archived. - `\Datetime createdAt` A timestamp in RFC 3339 format - `?string description` - `BetaManagedAgentsExecutionIdentity executionIdentity` Execution principal for runs of this agent. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `list mcpServers` - `array metadata` - `BetaManagedAgentsModelConfig model` Model identifier and configuration. - `?BetaManagedAgentsMultiagent multiagent` Multiagent orchestration configuration. Null when the agent is single-threaded. - `string name` - `list skills` - `?string system` - `list tools` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `int version` The agent's current version. Starts at 1 and increments when the agent is modified. #### Example ```php beta->agents->versions->list( 'agent_011CZkYpogX7uDKUyvBTophP', limit: 0, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->environments->create(string name, ?Config config, ?string description, ?array metadata, ?Scope scope, ?list betas, ?string workspaceID): BetaEnvironment` **POST** `/v1/environments` Create a new environment with the specified configuration. #### Parameters - `name: string` Human-readable name for the environment - `config?: optional Config` Environment configuration - `description?: optional string` Optional description of the environment - `metadata?: optional array` User-provided metadata key-value pairs - `scope?: optional Scope` 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. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaEnvironment` - `"environment" type` The type of object (always 'environment') - `string id` Environment identifier (e.g., 'env_...') - `?string archivedAt` RFC 3339 timestamp when environment was archived, or null if not archived - `Config config` Environment configuration (either Anthropic Cloud or self-hosted) - `string createdAt` RFC 3339 timestamp when environment was created - `?string description` User-provided description for the environment; null when unset - `array metadata` User-provided metadata key-value pairs - `string name` Human-readable name for the environment - `string updatedAt` RFC 3339 timestamp when environment was last updated - `?Scope scope` The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. #### Example ```php beta->environments->create( name: 'python-data-analysis', config: [ 'type' => 'cloud', 'networking' => [ 'type' => 'limited', 'allowMCPServers' => true, 'allowPackageManagers' => true, 'allowedHosts' => ['api.example.com'], ], 'packages' => [ 'apt' => ['string'], 'cargo' => ['string'], 'gem' => ['string'], 'go' => ['string'], 'npm' => ['string'], 'pip' => ['pandas', 'numpy'], 'type' => 'packages', ], ], description: 'Python environment with data-analysis packages.', metadata: ['foo' => 'string'], scope: 'organization', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaEnvironment); ``` ##### 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 `$client->beta->environments->list(?bool includeArchived, ?int limit, ?string page, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/environments` List environments with pagination support. #### Parameters - `includeArchived?: optional bool` (query parameter) Include archived environments in the response default: false - `limit?: optional int` (query parameter) Maximum number of environments to return default: 20 - `page?: optional string` (query parameter) Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaEnvironment` - `"environment" type` The type of object (always 'environment') - `string id` Environment identifier (e.g., 'env_...') - `?string archivedAt` RFC 3339 timestamp when environment was archived, or null if not archived - `Config config` Environment configuration (either Anthropic Cloud or self-hosted) - `string createdAt` RFC 3339 timestamp when environment was created - `?string description` User-provided description for the environment; null when unset - `array metadata` User-provided metadata key-value pairs - `string name` Human-readable name for the environment - `string updatedAt` RFC 3339 timestamp when environment was last updated - `?Scope scope` The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. #### Example ```php beta->environments->list( includeArchived: true, limit: 1, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->environments->retrieve(string environmentID, ?list betas, ?string workspaceID): BetaEnvironment` **GET** `/v1/environments/{environment_id}` Retrieve a specific environment by ID. #### Parameters - `environmentID: string` (path parameter) - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaEnvironment` - `"environment" type` The type of object (always 'environment') - `string id` Environment identifier (e.g., 'env_...') - `?string archivedAt` RFC 3339 timestamp when environment was archived, or null if not archived - `Config config` Environment configuration (either Anthropic Cloud or self-hosted) - `string createdAt` RFC 3339 timestamp when environment was created - `?string description` User-provided description for the environment; null when unset - `array metadata` User-provided metadata key-value pairs - `string name` Human-readable name for the environment - `string updatedAt` RFC 3339 timestamp when environment was last updated - `?Scope scope` The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. #### Example ```php beta->environments->retrieve( 'env_011CZkZ9X2dpNyB7HsEFoRfW', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaEnvironment); ``` ##### 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 `$client->beta->environments->update(string environmentID, ?Config config, ?string description, ?array metadata, ?string name, ?Scope scope, ?list betas, ?string workspaceID): BetaEnvironment` **POST** `/v1/environments/{environment_id}` Update an existing environment's configuration. #### Parameters - `environmentID: string` (path parameter) - `config?: optional Config` 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. - `metadata?: optional array` 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 - `scope?: optional Scope` The visibility scope for this environment. 'organization' makes the environment visible to all accounts. 'account' restricts visibility to the owning account only. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaEnvironment` - `"environment" type` The type of object (always 'environment') - `string id` Environment identifier (e.g., 'env_...') - `?string archivedAt` RFC 3339 timestamp when environment was archived, or null if not archived - `Config config` Environment configuration (either Anthropic Cloud or self-hosted) - `string createdAt` RFC 3339 timestamp when environment was created - `?string description` User-provided description for the environment; null when unset - `array metadata` User-provided metadata key-value pairs - `string name` Human-readable name for the environment - `string updatedAt` RFC 3339 timestamp when environment was last updated - `?Scope scope` The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. #### Example ```php beta->environments->update( 'env_011CZkZ9X2dpNyB7HsEFoRfW', config: [ 'type' => 'cloud', 'networking' => [ 'type' => 'limited', 'allowMCPServers' => true, 'allowPackageManagers' => true, 'allowedHosts' => ['api.example.com'], ], 'packages' => [ 'apt' => ['string'], 'cargo' => ['string'], 'gem' => ['string'], 'go' => ['string'], 'npm' => ['string'], 'pip' => ['pandas', 'numpy'], 'type' => 'packages', ], ], description: 'Python environment with data-analysis packages.', metadata: ['foo' => 'string'], name: 'x', scope: 'organization', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaEnvironment); ``` ##### 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 `$client->beta->environments->delete(string environmentID, ?list betas, ?string workspaceID): BetaEnvironmentDeleteResponse` **DELETE** `/v1/environments/{environment_id}` Delete an environment by ID. Returns a confirmation of the deletion. #### Parameters - `environmentID: string` (path parameter) - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaEnvironmentDeleteResponse` - `"environment_deleted" type` The type of response - `string id` Environment identifier #### Example ```php beta->environments->delete( 'env_011CZkZ9X2dpNyB7HsEFoRfW', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaEnvironmentDeleteResponse); ``` ##### Response (200) ```json { "id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "type": "environment_deleted" } ``` ### Archive Environment `$client->beta->environments->archive(string environmentID, ?list betas, ?string workspaceID): BetaEnvironment` **POST** `/v1/environments/{environment_id}/archive` Archive an environment by ID. Archived environments cannot be used to create new sessions. #### Parameters - `environmentID: string` (path parameter) - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaEnvironment` - `"environment" type` The type of object (always 'environment') - `string id` Environment identifier (e.g., 'env_...') - `?string archivedAt` RFC 3339 timestamp when environment was archived, or null if not archived - `Config config` Environment configuration (either Anthropic Cloud or self-hosted) - `string createdAt` RFC 3339 timestamp when environment was created - `?string description` User-provided description for the environment; null when unset - `array metadata` User-provided metadata key-value pairs - `string name` Human-readable name for the environment - `string updatedAt` RFC 3339 timestamp when environment was last updated - `?Scope scope` The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. #### Example ```php beta->environments->archive( 'env_011CZkZ9X2dpNyB7HsEFoRfW', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaEnvironment); ``` ##### 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 `$client->beta->environments->work->retrieve(string workID, string environmentID, ?list betas, ?string workspaceID): SelfHostedWork` **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 - `environmentID: string` (path parameter) - `workID: string` (path parameter) - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class SelfHostedWork` - `"work" type` The type of object (always 'work') - `string id` Work identifier (e.g., 'work_...') - `?string acknowledgedAt` RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - `string createdAt` RFC 3339 timestamp when work was created - `SessionWorkData data` The actual work to be performed - `string environmentID` Environment identifier this work belongs to (e.g., `env_...`) - `?string latestHeartbeatAt` RFC 3339 timestamp of the most recent heartbeat - `array metadata` User-provided metadata key-value pairs associated with this work item - `?string secret` 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. - `?string startedAt` RFC 3339 timestamp when work execution started - `State state` Current state of the work item - `?string stopRequestedAt` RFC 3339 timestamp when stop was requested - `?string stoppedAt` RFC 3339 timestamp when work execution stopped #### Example ```php beta->environments->work->retrieve( 'work_id', environmentID: 'env_011CZkZ9X2dpNyB7HsEFoRfW', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaSelfHostedWork); ``` ##### 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 `$client->beta->environments->work->poll(string environmentID, ?int blockMs, ?int reclaimOlderThanMs, ?list betas, ?string anthropicWorkerID): SelfHostedWork` **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 - `environmentID: string` (path parameter) - `blockMs?: optional int` (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). - `reclaimOlderThanMs?: optional int` (query parameter) Reclaim unacknowledged work items older than this many milliseconds. If omitted, uses the default (5000ms). - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `anthropicWorkerID?: optional string` (header parameter) Unique identifier for the specific worker polling, used to track aggregated environment-level work metrics in Console #### Returns - `class SelfHostedWork` - `"work" type` The type of object (always 'work') - `string id` Work identifier (e.g., 'work_...') - `?string acknowledgedAt` RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - `string createdAt` RFC 3339 timestamp when work was created - `SessionWorkData data` The actual work to be performed - `string environmentID` Environment identifier this work belongs to (e.g., `env_...`) - `?string latestHeartbeatAt` RFC 3339 timestamp of the most recent heartbeat - `array metadata` User-provided metadata key-value pairs associated with this work item - `?string secret` 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. - `?string startedAt` RFC 3339 timestamp when work execution started - `State state` Current state of the work item - `?string stopRequestedAt` RFC 3339 timestamp when stop was requested - `?string stoppedAt` RFC 3339 timestamp when work execution stopped #### Example ```php beta->environments->work->poll( 'env_011CZkZ9X2dpNyB7HsEFoRfW', blockMs: 1, reclaimOlderThanMs: 1, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], anthropicWorkerID: 'Anthropic-Worker-ID', ); var_dump($betaSelfHostedWork); ``` ##### 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 `$client->beta->environments->work->ack(string workID, string environmentID, ?list betas): SelfHostedWork` **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 - `environmentID: string` (path parameter) - `workID: string` (path parameter) - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class SelfHostedWork` - `"work" type` The type of object (always 'work') - `string id` Work identifier (e.g., 'work_...') - `?string acknowledgedAt` RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - `string createdAt` RFC 3339 timestamp when work was created - `SessionWorkData data` The actual work to be performed - `string environmentID` Environment identifier this work belongs to (e.g., `env_...`) - `?string latestHeartbeatAt` RFC 3339 timestamp of the most recent heartbeat - `array metadata` User-provided metadata key-value pairs associated with this work item - `?string secret` 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. - `?string startedAt` RFC 3339 timestamp when work execution started - `State state` Current state of the work item - `?string stopRequestedAt` RFC 3339 timestamp when stop was requested - `?string stoppedAt` RFC 3339 timestamp when work execution stopped #### Example ```php beta->environments->work->ack( 'work_id', environmentID: 'env_011CZkZ9X2dpNyB7HsEFoRfW', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaSelfHostedWork); ``` ##### 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 `$client->beta->environments->work->heartbeat(string workID, string environmentID, ?int desiredTTLSeconds, ?string expectedLastHeartbeat, ?list betas): SelfHostedWorkHeartbeatResponse` **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 - `environmentID: string` (path parameter) - `workID: string` (path parameter) - `desiredTTLSeconds?: optional int` (query parameter) Desired TTL in seconds - `expectedLastHeartbeat?: 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. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class SelfHostedWorkHeartbeatResponse` - `"work_heartbeat" type` The type of response - `string lastHeartbeat` RFC 3339 timestamp of the most recent heartbeat recorded for this work item, or an empty string if none has been recorded - `bool leaseExtended` Whether the heartbeat succeeded in extending the lease - `State state` Current state of the work item (active/stopping/stopped) - `int ttlSeconds` Effective TTL applied to the lease #### Example ```php beta ->environments ->work ->heartbeat( 'work_id', environmentID: 'env_011CZkZ9X2dpNyB7HsEFoRfW', desiredTTLSeconds: 0, expectedLastHeartbeat: 'expected_last_heartbeat', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaSelfHostedWorkHeartbeatResponse); ``` ##### Response (200) ```json { "last_heartbeat": "last_heartbeat", "lease_extended": true, "state": "queued", "ttl_seconds": 0, "type": "work_heartbeat" } ``` ### Stop Work `$client->beta->environments->work->stop(string workID, string environmentID, ?bool force, ?list betas, ?string workspaceID): SelfHostedWork` **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 - `environmentID: string` (path parameter) - `workID: string` (path parameter) - `force?: optional bool` If true, immediately stop work without graceful shutdown default: false - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class SelfHostedWork` - `"work" type` The type of object (always 'work') - `string id` Work identifier (e.g., 'work_...') - `?string acknowledgedAt` RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - `string createdAt` RFC 3339 timestamp when work was created - `SessionWorkData data` The actual work to be performed - `string environmentID` Environment identifier this work belongs to (e.g., `env_...`) - `?string latestHeartbeatAt` RFC 3339 timestamp of the most recent heartbeat - `array metadata` User-provided metadata key-value pairs associated with this work item - `?string secret` 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. - `?string startedAt` RFC 3339 timestamp when work execution started - `State state` Current state of the work item - `?string stopRequestedAt` RFC 3339 timestamp when stop was requested - `?string stoppedAt` RFC 3339 timestamp when work execution stopped #### Example ```php beta->environments->work->stop( 'work_id', environmentID: 'env_011CZkZ9X2dpNyB7HsEFoRfW', force: true, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaSelfHostedWork); ``` ##### 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 `$client->beta->environments->work->list(string environmentID, ?int limit, ?string page, ?list betas): PageCursor` **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 - `environmentID: string` (path parameter) - `limit?: optional int` (query parameter) Maximum number of work items to return default: 20 - `page?: optional string` (query parameter) Opaque cursor from previous response for pagination - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class SelfHostedWork` - `"work" type` The type of object (always 'work') - `string id` Work identifier (e.g., 'work_...') - `?string acknowledgedAt` RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - `string createdAt` RFC 3339 timestamp when work was created - `SessionWorkData data` The actual work to be performed - `string environmentID` Environment identifier this work belongs to (e.g., `env_...`) - `?string latestHeartbeatAt` RFC 3339 timestamp of the most recent heartbeat - `array metadata` User-provided metadata key-value pairs associated with this work item - `?string secret` 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. - `?string startedAt` RFC 3339 timestamp when work execution started - `State state` Current state of the work item - `?string stopRequestedAt` RFC 3339 timestamp when stop was requested - `?string stoppedAt` RFC 3339 timestamp when work execution stopped #### Example ```php beta->environments->work->list( 'env_011CZkZ9X2dpNyB7HsEFoRfW', limit: 1, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### 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 `$client->beta->environments->work->update(string workID, string environmentID, array metadata, ?list betas, ?string workspaceID): SelfHostedWork` **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 - `environmentID: string` (path parameter) - `workID: string` (path parameter) - `metadata: array` Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve existing metadata. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class SelfHostedWork` - `"work" type` The type of object (always 'work') - `string id` Work identifier (e.g., 'work_...') - `?string acknowledgedAt` RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - `string createdAt` RFC 3339 timestamp when work was created - `SessionWorkData data` The actual work to be performed - `string environmentID` Environment identifier this work belongs to (e.g., `env_...`) - `?string latestHeartbeatAt` RFC 3339 timestamp of the most recent heartbeat - `array metadata` User-provided metadata key-value pairs associated with this work item - `?string secret` 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. - `?string startedAt` RFC 3339 timestamp when work execution started - `State state` Current state of the work item - `?string stopRequestedAt` RFC 3339 timestamp when stop was requested - `?string stoppedAt` RFC 3339 timestamp when work execution stopped #### Example ```php beta->environments->work->update( 'work_id', environmentID: 'env_011CZkZ9X2dpNyB7HsEFoRfW', metadata: ['foo' => 'string'], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaSelfHostedWork); ``` ##### 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 `$client->beta->environments->work->stats(string environmentID, ?list betas, ?string workspaceID): SelfHostedWorkQueueStats` **GET** `/v1/environments/{environment_id}/work/stats` Get statistics about the work queue for an environment. #### Parameters - `environmentID: string` (path parameter) - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class SelfHostedWorkQueueStats` - `"work_queue_stats" type` The type of object - `int depth` Number of work items waiting to be picked up - `?string oldestQueuedAt` RFC 3339 timestamp of oldest item in the work stream (includes both queued and pending items), null if stream empty - `int pending` Number of work items being processed (polled but not acknowledged) - `?int workersPolling` Number of workers that have polled for work in the last 30 seconds. Requires worker_id to be sent with poll requests. #### Example ```php beta->environments->work->stats( 'env_011CZkZ9X2dpNyB7HsEFoRfW', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaSelfHostedWorkQueueStats); ``` ##### Response (200) ```json { "depth": 0, "oldest_queued_at": "oldest_queued_at", "pending": 0, "type": "work_queue_stats", "workers_polling": 0 } ``` ## Beta › Sessions ### Create Session `$client->beta->sessions->create(Agent agent, string environmentID, ?BetaManagedAgentsBudgetLimit budget, ?list initialEvents, ?array metadata, ?list resources, ?string title, ?list vaultIDs, ?list betas, ?string workspaceID): BetaManagedAgentsSession` **POST** `/v1/sessions` Create Session #### Parameters - `agent: Agent` Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. - `environmentID: string` ID of the `environment` defining the container configuration for this session. - `budget?: optional BetaManagedAgentsBudgetLimit` 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`. - `initialEvents?: optional list` 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 array` Arbitrary key-value metadata attached to the session. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `resources?: optional list` Resources (e.g. repositories, files) to mount into the session's container. - `title?: optional string` Human-readable session title. - `vaultIDs?: optional list` Vault IDs for stored credentials the agent can use during the session. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsSession` - `"session" type` - `string id` - `BetaManagedAgentsSessionAgent agent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `?\Datetime archivedAt` When the session was archived. Null if not archived. - `?BetaManagedAgentsBudgetLimit budget` The session's enforced spend ceiling, or null when no budget is set. - `\Datetime createdAt` A timestamp in RFC 3339 format - `string environmentID` - `array metadata` - `list outcomeEvaluations` Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. - `list resources` - `BetaManagedAgentsSessionStats stats` Timing statistics for the session. - `Status status` - `?string title` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `BetaManagedAgentsSessionUsage usage` Cumulative token usage for the session. - `list vaultIDs` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `?string deploymentID` Deployment ID when the session was created from a deployment reference. Null otherwise. #### Example ```php beta->sessions->create( agent: 'agent_011CZkYpogX7uDKUyvBTophP', environmentID: 'env_011CZkZ9X2dpNyB7HsEFoRfW', budget: [ 'maxListCost' => ['amount' => '2500', 'currency' => BetaCurrency::USD], 'type' => 'limit', ], initialEvents: [ [ 'content' => [['text' => 'Where is my order #1234?', 'type' => 'text']], 'type' => 'user.message', ], ], metadata: ['foo' => 'string'], resources: [ [ 'fileID' => 'file_011CNha8iCJcU1wXNR6q4V8w', 'type' => 'file', 'mountPath' => '/uploads/receipt.pdf', ], ], title: 'Order #1234 inquiry', vaultIDs: ['string'], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsSession); ``` ##### 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 `$client->beta->sessions->list(?string agentID, ?int agentVersion, ?\Datetime createdAtGt, ?\Datetime createdAtGte, ?\Datetime createdAtLt, ?\Datetime createdAtLte, ?string deploymentID, ?bool includeArchived, ?int limit, ?string memoryStoreID, ?Order order, ?string page, ?list statuses, ?list betas, ?string workspaceID): BidirectionalPageCursor` **GET** `/v1/sessions` List Sessions #### Parameters - `agentID?: optional string` (query parameter) Filter sessions created with this agent ID. - `agentVersion?: optional int` (query parameter) Filter by agent version. Only applies when `agent_id` is also set. - `createdAtGt?: optional \Datetime` (query parameter) Return sessions created after this time (exclusive). - `createdAtGte?: optional \Datetime` (query parameter) Return sessions created at or after this time (inclusive). - `createdAtLt?: optional \Datetime` (query parameter) Return sessions created before this time (exclusive). - `createdAtLte?: optional \Datetime` (query parameter) Return sessions created at or before this time (inclusive). - `deploymentID?: optional string` (query parameter) Filter sessions created by this deployment ID. - `includeArchived?: optional bool` (query parameter) When true, includes archived sessions. Default: false (exclude archived). - `limit?: optional int` (query parameter) Maximum number of results to return. - `memoryStoreID?: optional string` (query parameter) Filter sessions whose resources contain a `memory_store` with this memory store ID. - `order?: optional Order` (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. - `statuses?: optional list` (query parameter) Filter by session status. Repeat the parameter to match any of multiple statuses. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsSession` - `"session" type` - `string id` - `BetaManagedAgentsSessionAgent agent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `?\Datetime archivedAt` When the session was archived. Null if not archived. - `?BetaManagedAgentsBudgetLimit budget` The session's enforced spend ceiling, or null when no budget is set. - `\Datetime createdAt` A timestamp in RFC 3339 format - `string environmentID` - `array metadata` - `list outcomeEvaluations` Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. - `list resources` - `BetaManagedAgentsSessionStats stats` Timing statistics for the session. - `Status status` - `?string title` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `BetaManagedAgentsSessionUsage usage` Cumulative token usage for the session. - `list vaultIDs` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `?string deploymentID` Deployment ID when the session was created from a deployment reference. Null otherwise. #### Example ```php beta->sessions->list( agentID: 'agent_id', agentVersion: 0, createdAtGt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtGte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtLt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtLte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), deploymentID: 'deployment_id', includeArchived: true, limit: 0, memoryStoreID: 'memory_store_id', order: 'asc', page: 'page', statuses: ['rescheduling'], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->sessions->retrieve(string sessionID, ?list betas, ?string workspaceID): BetaManagedAgentsSession` **GET** `/v1/sessions/{session_id}` Get Session #### Parameters - `sessionID: string` (path parameter) - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsSession` - `"session" type` - `string id` - `BetaManagedAgentsSessionAgent agent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `?\Datetime archivedAt` When the session was archived. Null if not archived. - `?BetaManagedAgentsBudgetLimit budget` The session's enforced spend ceiling, or null when no budget is set. - `\Datetime createdAt` A timestamp in RFC 3339 format - `string environmentID` - `array metadata` - `list outcomeEvaluations` Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. - `list resources` - `BetaManagedAgentsSessionStats stats` Timing statistics for the session. - `Status status` - `?string title` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `BetaManagedAgentsSessionUsage usage` Cumulative token usage for the session. - `list vaultIDs` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `?string deploymentID` Deployment ID when the session was created from a deployment reference. Null otherwise. #### Example ```php beta->sessions->retrieve( 'sesn_011CZkZAtmR3yMPDzynEDxu7', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsSession); ``` ##### 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 `$client->beta->sessions->update(string sessionID, ?BetaManagedAgentsSessionAgentUpdate agent, ?BetaManagedAgentsBudgetLimit budget, ?array metadata, ?string title, ?list vaultIDs, ?list betas, ?string workspaceID): BetaManagedAgentsSession` **POST** `/v1/sessions/{session_id}` Update Session #### Parameters - `sessionID: string` (path parameter) - `agent?: optional BetaManagedAgentsSessionAgentUpdate` 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 BetaManagedAgentsBudgetLimit` 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 array` 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. - `vaultIDs?: optional list` Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsSession` - `"session" type` - `string id` - `BetaManagedAgentsSessionAgent agent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `?\Datetime archivedAt` When the session was archived. Null if not archived. - `?BetaManagedAgentsBudgetLimit budget` The session's enforced spend ceiling, or null when no budget is set. - `\Datetime createdAt` A timestamp in RFC 3339 format - `string environmentID` - `array metadata` - `list outcomeEvaluations` Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. - `list resources` - `BetaManagedAgentsSessionStats stats` Timing statistics for the session. - `Status status` - `?string title` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `BetaManagedAgentsSessionUsage usage` Cumulative token usage for the session. - `list vaultIDs` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `?string deploymentID` Deployment ID when the session was created from a deployment reference. Null otherwise. #### Example ```php beta->sessions->update( 'sesn_011CZkZAtmR3yMPDzynEDxu7', agent: [ 'mcpServers' => [ [ 'name' => 'example-mcp', 'type' => 'url', 'url' => 'https://example-server.modelcontextprotocol.io/sse', ], ], 'tools' => [ [ 'type' => 'agent_toolset_20260401', 'configs' => [ [ 'name' => 'bash', 'enabled' => true, 'permissionPolicy' => ['type' => 'always_allow'], 'type' => 'bash', ], ], 'defaultConfig' => [ 'enabled' => true, 'permissionPolicy' => ['type' => 'always_allow'] ], ], ], ], budget: [ 'maxListCost' => ['amount' => '2500', 'currency' => BetaCurrency::USD], 'type' => 'limit', ], metadata: ['foo' => 'string'], title: 'Order #1234 inquiry', vaultIDs: ['string'], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsSession); ``` ##### 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 `$client->beta->sessions->delete(string sessionID, ?list betas, ?string workspaceID): BetaManagedAgentsDeletedSession` **DELETE** `/v1/sessions/{session_id}` Delete Session #### Parameters - `sessionID: string` (path parameter) - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsDeletedSession` - `"session_deleted" type` - `string id` #### Example ```php beta->sessions->delete( 'sesn_011CZkZAtmR3yMPDzynEDxu7', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsDeletedSession); ``` ##### Response (200) ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "type": "session_deleted" } ``` ### Archive Session `$client->beta->sessions->archive(string sessionID, ?list betas, ?string workspaceID): BetaManagedAgentsSession` **POST** `/v1/sessions/{session_id}/archive` Archive Session #### Parameters - `sessionID: string` (path parameter) - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsSession` - `"session" type` - `string id` - `BetaManagedAgentsSessionAgent agent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `?\Datetime archivedAt` When the session was archived. Null if not archived. - `?BetaManagedAgentsBudgetLimit budget` The session's enforced spend ceiling, or null when no budget is set. - `\Datetime createdAt` A timestamp in RFC 3339 format - `string environmentID` - `array metadata` - `list outcomeEvaluations` Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. - `list resources` - `BetaManagedAgentsSessionStats stats` Timing statistics for the session. - `Status status` - `?string title` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `BetaManagedAgentsSessionUsage usage` Cumulative token usage for the session. - `list vaultIDs` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `?string deploymentID` Deployment ID when the session was created from a deployment reference. Null otherwise. #### Example ```php beta->sessions->archive( 'sesn_011CZkZAtmR3yMPDzynEDxu7', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsSession); ``` ##### 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 `$client->beta->sessions->events->list(string sessionID, ?\Datetime createdAtGt, ?\Datetime createdAtGte, ?\Datetime createdAtLt, ?\Datetime createdAtLte, ?int limit, ?Order order, ?string page, ?list types, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/sessions/{session_id}/events` List Events #### Parameters - `sessionID: string` (path parameter) - `createdAtGt?: optional \Datetime` (query parameter) Return events created after this time (exclusive). Compared against the event's `processed_at` value. - `createdAtGte?: optional \Datetime` (query parameter) Return events created at or after this time (inclusive). Compared against the event's `processed_at` value. - `createdAtLt?: optional \Datetime` (query parameter) Return events created before this time (exclusive). Compared against the event's `processed_at` value. - `createdAtLte?: optional \Datetime` (query parameter) Return events created at or before this time (inclusive). Compared against the event's `processed_at` value. - `limit?: optional int` (query parameter) - `order?: optional Order` (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`. - `types?: optional list` (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. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsSessionEvent` - `class ManagedAgentsUserMessageEvent` - `"user.message" type` - `string id` Unique identifier for this event. - `list content` Array of content blocks comprising the user message. - `?\Datetime processedAt` Timestamp when the agent finished processing this message. - `class ManagedAgentsUserInterruptEvent` - `"user.interrupt" type` - `string id` Unique identifier for this event. - `?\Datetime processedAt` Timestamp when the interrupt was processed. - `?string sessionThreadID` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `class ManagedAgentsUserToolConfirmationEvent` - `"user.tool_confirmation" type` - `string id` Unique identifier for this event. - `Result result` The confirmation result: 'allow' or 'deny'. - `string toolUseID` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=php#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `?string denyMessage` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `?\Datetime processedAt` Timestamp when the confirmation was processed. - `?string sessionThreadID` Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread. - `class ManagedAgentsUserCustomToolResultEvent` - `"user.custom_tool_result" type` - `string id` Unique identifier for this event. - `string customToolUseID` 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=php#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` Timestamp when this result was processed. - `?string sessionThreadID` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `class ManagedAgentsAgentCustomToolUseEvent` - `"agent.custom_tool_use" type` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the custom tool being called. - `\Datetime processedAt` Timestamp when this tool use was processed. - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.custom_tool_result` by `custom_tool_use_id`, so clients do not send it back. - `class ManagedAgentsAgentMessageEvent` - `"agent.message" type` - `string id` Unique identifier for this event. - `list content` Array of text blocks comprising the agent response. - `\Datetime processedAt` Timestamp when this response was generated. - `class ManagedAgentsAgentThinkingEvent` - `"agent.thinking" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this thinking was produced. - `class ManagedAgentsAgentMCPToolUseEvent` - `"agent.mcp_tool_use" type` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string mcpServerName` Name of the MCP server providing the tool. - `string name` Name of the MCP tool being used. - `\Datetime processedAt` Timestamp when this event was processed. - `?ManagedAgentsAgentEvaluatedPermission evaluatedPermission` The evaluated permission policy for this tool invocation. - `?ManagedAgentsAgentToolEvaluation evaluation` 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). - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.tool_confirmation` by `tool_use_id`, so clients do not send it back. - `class ManagedAgentsAgentMCPToolResultEvent` - `"agent.mcp_tool_result" type` - `string id` Unique identifier for this event. - `string mcpToolUseID` The id of the `agent.mcp_tool_use` event this result corresponds to. - `\Datetime processedAt` Timestamp when this event was processed. - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `class ManagedAgentsAgentToolUseEvent` - `"agent.tool_use" type` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the agent tool being used. - `\Datetime processedAt` Timestamp when this event was processed. - `?ManagedAgentsAgentEvaluatedPermission evaluatedPermission` The evaluated permission policy for this tool invocation. - `?ManagedAgentsAgentToolEvaluation evaluation` 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). - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. 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. - `class ManagedAgentsAgentToolResultEvent` - `"agent.tool_result" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this event was processed. - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to. - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `class ManagedAgentsAgentThreadMessageReceivedEvent` - `"agent.thread_message_received" type` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `string fromSessionThreadID` Public `sthr_` ID of the thread that sent the message. - `\Datetime processedAt` Timestamp when the message was received. - `?string fromAgentName` Name of the callable agent this message came from. Absent when received from the primary agent. - `class ManagedAgentsAgentThreadMessageSentEvent` - `"agent.thread_message_sent" type` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `\Datetime processedAt` Timestamp when the message was sent. - `string toSessionThreadID` Public `sthr_` ID of the thread the message was sent to. - `?string toAgentName` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `class ManagedAgentsAgentThreadContextCompactedEvent` - `"agent.thread_context_compacted" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when compaction was processed. - `class ManagedAgentsSessionErrorEvent` - `"session.error" type` - `string id` Unique identifier for this event. - `Error error` - `\Datetime processedAt` Timestamp when the error occurred. - `class ManagedAgentsSessionStatusRescheduledEvent` - `"session.status_rescheduled" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp of status change. - `class ManagedAgentsSessionStatusRunningEvent` - `"session.status_running" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp of status change. - `class ManagedAgentsSessionStatusIdleEvent` - `"session.status_idle" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp of status change. - `?ManagedAgentsSessionRefusalStopDetails stopDetails` Structured information about why the session stopped. `null` when there is nothing more to report. - `StopReason stopReason` - `class ManagedAgentsSessionStatusTerminatedEvent` - `"session.status_terminated" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp of status change. - `class ManagedAgentsSessionThreadCreatedEvent` - `"session.thread_created" type` - `string id` Unique identifier for this event. - `string agentName` Name of the callable agent the thread runs. - `\Datetime processedAt` Timestamp when the thread was created. - `string sessionThreadID` Public `sthr_` ID of the newly created thread. - `?string workflowRunID` Identifier of the workflow run that created the thread, or `null` for any other thread. - `class ManagedAgentsSpanOutcomeEvaluationStartEvent` - `"span.outcome_evaluation_start" type` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` Timestamp when outcome evaluation started. - `class ManagedAgentsSpanOutcomeEvaluationEndEvent` - `"span.outcome_evaluation_end" type` - `string id` Unique identifier for this event. - `string explanation` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeEvaluationStartID` The id of the corresponding `span.outcome_evaluation_start` event. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` Timestamp when outcome evaluation ended. - `string result` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `ManagedAgentsSpanModelUsage usage` Aggregate token usage for this evaluation cycle. Sums across all grader model requests within the cycle. - `class ManagedAgentsSpanModelRequestStartEvent` - `"span.model_request_start" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when the model request started. - `class ManagedAgentsSpanModelRequestEndEvent` - `"span.model_request_end" type` - `string id` Unique identifier for this event. - `?bool isError` Whether the model request resulted in an error. - `string modelRequestStartID` The id of the corresponding `span.model_request_start` event. - `ManagedAgentsSpanModelUsage modelUsage` Token usage for this model request. - `\Datetime processedAt` Timestamp when the model request completed. - `class ManagedAgentsSpanOutcomeEvaluationOngoingEvent` - `"span.outcome_evaluation_ongoing" type` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` Timestamp when this heartbeat was emitted. - `class ManagedAgentsUserDefineOutcomeEvent` - `"user.define_outcome" type` - `string id` Unique identifier for this event. - `string description` What the agent should produce. Copied from the input event. - `?int maxIterations` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `string outcomeID` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `\Datetime processedAt` Timestamp when the outcome was accepted. - `Rubric rubric` How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants. - `class ManagedAgentsSessionDeletedEvent` - `"session.deleted" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when the session was deleted. - `class ManagedAgentsSessionThreadStatusRunningEvent` - `"session.thread_status_running" type` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` Timestamp of the status transition. - `string sessionThreadID` Public sthr_ ID of the thread that started running. - `class ManagedAgentsSessionThreadStatusIdleEvent` - `"session.thread_status_idle" type` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` Timestamp of the status transition. - `string sessionThreadID` Public sthr_ ID of the thread that went idle. - `?ManagedAgentsSessionRefusalStopDetails stopDetails` Structured information about why the thread stopped. `null` when there is nothing more to report. - `StopReason stopReason` - `class ManagedAgentsSessionThreadStatusTerminatedEvent` - `"session.thread_status_terminated" type` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` Timestamp of the status transition. - `string sessionThreadID` Public sthr_ ID of the thread that terminated. - `class BetaManagedAgentsUserToolResultEvent` - `"user.tool_result" type` - `string id` Unique identifier for this event. - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=php#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` Timestamp when this result was processed. - `?string sessionThreadID` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `class ManagedAgentsSessionThreadStatusRescheduledEvent` - `"session.thread_status_rescheduled" type` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` Timestamp of the status transition. - `string sessionThreadID` Public sthr_ ID of the thread that is retrying. - `class BetaManagedAgentsSessionUpdatedEvent` - `"session.updated" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when the update was applied. - `?BetaManagedAgentsSessionAgent agent` 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. - `?BetaManagedAgentsBudgetLimit budget` 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. - `?array metadata` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `?string title` The session's new title. Present only when the update changed it. - `class BetaManagedAgentsSystemMessageEvent` - `"system.message" type` - `string id` Unique identifier for this event. - `list content` System content blocks. Text-only. - `?\Datetime processedAt` Timestamp when this system message was processed. - `class BetaManagedAgentsSessionUsageEvent` - `"session.usage" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when the snapshot was taken. - `ManagedAgentsSessionUsageSnapshot usage` The session's cumulative usage at the snapshot time. - `?BetaManagedAgentsBudgetLimit budget` The session's configured budget at the snapshot time, or null when the session has no budget. - `class ManagedAgentsWorkflowRunCreatedEvent` - `"workflow_run.created" type` - `string id` Unique identifier for this event. - `?string description` Description that the agent gave the run, passed on as written, or `null` if it gave none. - `string name` Name that the agent gave the run, passed on as written, or a name that the server assigned. - `list phases` The phases that the run's plan declares, in the plan's order. Can be empty. - `\Datetime processedAt` Timestamp when this event was processed. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `class ManagedAgentsWorkflowRunStatusEndedEvent` - `"workflow_run.status_ended" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this event was processed. - `ManagedAgentsWorkflowRunResult result` How the run ended. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `class ManagedAgentsWorkflowRunPhaseStartedEvent` - `"workflow_run.phase_started" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this event was processed. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `string workflowRunPhaseID` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `class ManagedAgentsWorkflowRunPhaseEndedEvent` - `"workflow_run.phase_ended" type` - `string id` Unique identifier for this event. - `string phaseStartedID` Identifier of the `workflow_run.phase_started` event that opened the phase. - `\Datetime processedAt` Timestamp when this event was processed. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `string workflowRunPhaseID` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `class ManagedAgentsWorkflowRunStatusRunningEvent` - `"workflow_run.status_running" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this event was processed. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `class ManagedAgentsWorkflowRunStatusIdleEvent` - `"workflow_run.status_idle" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this event was processed. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `class ManagedAgentsWorkflowRunErrorEvent` - `"workflow_run.error" type` - `string id` Unique identifier for this event. - `ManagedAgentsWorkflowRunError error` Why the run did not finish, or was not created. - `\Datetime processedAt` Timestamp when this event was processed. - `?string workflowRunID` Identifier of the run that met the error, or `null` when the error kept a run from being created. #### Example ```php beta->sessions->events->list( 'sesn_011CZkZAtmR3yMPDzynEDxu7', createdAtGt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtGte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtLt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtLte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), limit: 0, order: 'asc', page: 'page', types: [ManagedAgentsSessionEventType::USER_MESSAGE], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->sessions->events->send(string sessionID, list events, ?list betas, ?string workspaceID): ManagedAgentsSendSessionEvents` **POST** `/v1/sessions/{session_id}/events` Send Events #### Parameters - `sessionID: string` (path parameter) - `events: list` Events to send to the `session`. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsSendSessionEvents` - `?list data` Sent events #### Example ```php beta->sessions->events->send( 'sesn_011CZkZAtmR3yMPDzynEDxu7', events: [ [ 'content' => [['text' => 'Where is my order #1234?', 'type' => 'text']], 'type' => 'user.message', ], ], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsSendSessionEvents); ``` ##### 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 `$client->beta->sessions->events->streamStream(string sessionID, ?list eventDeltas, ?list betas, ?string workspaceID): BaseStream` **GET** `/v1/sessions/{session_id}/events/stream` Stream Events #### Parameters - `sessionID: string` (path parameter) - `eventDeltas?: optional list` (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. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsStreamSessionEvents` - `class ManagedAgentsUserMessageEvent` - `"user.message" type` - `string id` Unique identifier for this event. - `list content` Array of content blocks comprising the user message. - `?\Datetime processedAt` Timestamp when the agent finished processing this message. - `class ManagedAgentsUserInterruptEvent` - `"user.interrupt" type` - `string id` Unique identifier for this event. - `?\Datetime processedAt` Timestamp when the interrupt was processed. - `?string sessionThreadID` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `class ManagedAgentsUserToolConfirmationEvent` - `"user.tool_confirmation" type` - `string id` Unique identifier for this event. - `Result result` The confirmation result: 'allow' or 'deny'. - `string toolUseID` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=php#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `?string denyMessage` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `?\Datetime processedAt` Timestamp when the confirmation was processed. - `?string sessionThreadID` Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread. - `class ManagedAgentsUserCustomToolResultEvent` - `"user.custom_tool_result" type` - `string id` Unique identifier for this event. - `string customToolUseID` 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=php#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` Timestamp when this result was processed. - `?string sessionThreadID` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `class ManagedAgentsAgentCustomToolUseEvent` - `"agent.custom_tool_use" type` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the custom tool being called. - `\Datetime processedAt` Timestamp when this tool use was processed. - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.custom_tool_result` by `custom_tool_use_id`, so clients do not send it back. - `class ManagedAgentsAgentMessageEvent` - `"agent.message" type` - `string id` Unique identifier for this event. - `list content` Array of text blocks comprising the agent response. - `\Datetime processedAt` Timestamp when this response was generated. - `class ManagedAgentsAgentThinkingEvent` - `"agent.thinking" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this thinking was produced. - `class ManagedAgentsAgentMCPToolUseEvent` - `"agent.mcp_tool_use" type` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string mcpServerName` Name of the MCP server providing the tool. - `string name` Name of the MCP tool being used. - `\Datetime processedAt` Timestamp when this event was processed. - `?ManagedAgentsAgentEvaluatedPermission evaluatedPermission` The evaluated permission policy for this tool invocation. - `?ManagedAgentsAgentToolEvaluation evaluation` 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). - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.tool_confirmation` by `tool_use_id`, so clients do not send it back. - `class ManagedAgentsAgentMCPToolResultEvent` - `"agent.mcp_tool_result" type` - `string id` Unique identifier for this event. - `string mcpToolUseID` The id of the `agent.mcp_tool_use` event this result corresponds to. - `\Datetime processedAt` Timestamp when this event was processed. - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `class ManagedAgentsAgentToolUseEvent` - `"agent.tool_use" type` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the agent tool being used. - `\Datetime processedAt` Timestamp when this event was processed. - `?ManagedAgentsAgentEvaluatedPermission evaluatedPermission` The evaluated permission policy for this tool invocation. - `?ManagedAgentsAgentToolEvaluation evaluation` 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). - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. 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. - `class ManagedAgentsAgentToolResultEvent` - `"agent.tool_result" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this event was processed. - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to. - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `class ManagedAgentsAgentThreadMessageReceivedEvent` - `"agent.thread_message_received" type` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `string fromSessionThreadID` Public `sthr_` ID of the thread that sent the message. - `\Datetime processedAt` Timestamp when the message was received. - `?string fromAgentName` Name of the callable agent this message came from. Absent when received from the primary agent. - `class ManagedAgentsAgentThreadMessageSentEvent` - `"agent.thread_message_sent" type` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `\Datetime processedAt` Timestamp when the message was sent. - `string toSessionThreadID` Public `sthr_` ID of the thread the message was sent to. - `?string toAgentName` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `class ManagedAgentsAgentThreadContextCompactedEvent` - `"agent.thread_context_compacted" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when compaction was processed. - `class ManagedAgentsSessionErrorEvent` - `"session.error" type` - `string id` Unique identifier for this event. - `Error error` - `\Datetime processedAt` Timestamp when the error occurred. - `class ManagedAgentsSessionStatusRescheduledEvent` - `"session.status_rescheduled" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp of status change. - `class ManagedAgentsSessionStatusRunningEvent` - `"session.status_running" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp of status change. - `class ManagedAgentsSessionStatusIdleEvent` - `"session.status_idle" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp of status change. - `?ManagedAgentsSessionRefusalStopDetails stopDetails` Structured information about why the session stopped. `null` when there is nothing more to report. - `StopReason stopReason` - `class ManagedAgentsSessionStatusTerminatedEvent` - `"session.status_terminated" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp of status change. - `class ManagedAgentsSessionThreadCreatedEvent` - `"session.thread_created" type` - `string id` Unique identifier for this event. - `string agentName` Name of the callable agent the thread runs. - `\Datetime processedAt` Timestamp when the thread was created. - `string sessionThreadID` Public `sthr_` ID of the newly created thread. - `?string workflowRunID` Identifier of the workflow run that created the thread, or `null` for any other thread. - `class ManagedAgentsSpanOutcomeEvaluationStartEvent` - `"span.outcome_evaluation_start" type` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` Timestamp when outcome evaluation started. - `class ManagedAgentsSpanOutcomeEvaluationEndEvent` - `"span.outcome_evaluation_end" type` - `string id` Unique identifier for this event. - `string explanation` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeEvaluationStartID` The id of the corresponding `span.outcome_evaluation_start` event. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` Timestamp when outcome evaluation ended. - `string result` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `ManagedAgentsSpanModelUsage usage` Aggregate token usage for this evaluation cycle. Sums across all grader model requests within the cycle. - `class ManagedAgentsSpanModelRequestStartEvent` - `"span.model_request_start" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when the model request started. - `class ManagedAgentsSpanModelRequestEndEvent` - `"span.model_request_end" type` - `string id` Unique identifier for this event. - `?bool isError` Whether the model request resulted in an error. - `string modelRequestStartID` The id of the corresponding `span.model_request_start` event. - `ManagedAgentsSpanModelUsage modelUsage` Token usage for this model request. - `\Datetime processedAt` Timestamp when the model request completed. - `class ManagedAgentsSpanOutcomeEvaluationOngoingEvent` - `"span.outcome_evaluation_ongoing" type` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` Timestamp when this heartbeat was emitted. - `class ManagedAgentsUserDefineOutcomeEvent` - `"user.define_outcome" type` - `string id` Unique identifier for this event. - `string description` What the agent should produce. Copied from the input event. - `?int maxIterations` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `string outcomeID` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `\Datetime processedAt` Timestamp when the outcome was accepted. - `Rubric rubric` How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants. - `class ManagedAgentsSessionDeletedEvent` - `"session.deleted" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when the session was deleted. - `class ManagedAgentsSessionThreadStatusRunningEvent` - `"session.thread_status_running" type` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` Timestamp of the status transition. - `string sessionThreadID` Public sthr_ ID of the thread that started running. - `class ManagedAgentsSessionThreadStatusIdleEvent` - `"session.thread_status_idle" type` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` Timestamp of the status transition. - `string sessionThreadID` Public sthr_ ID of the thread that went idle. - `?ManagedAgentsSessionRefusalStopDetails stopDetails` Structured information about why the thread stopped. `null` when there is nothing more to report. - `StopReason stopReason` - `class ManagedAgentsSessionThreadStatusTerminatedEvent` - `"session.thread_status_terminated" type` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` Timestamp of the status transition. - `string sessionThreadID` Public sthr_ ID of the thread that terminated. - `class BetaManagedAgentsUserToolResultEvent` - `"user.tool_result" type` - `string id` Unique identifier for this event. - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=php#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` Timestamp when this result was processed. - `?string sessionThreadID` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `class ManagedAgentsSessionThreadStatusRescheduledEvent` - `"session.thread_status_rescheduled" type` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` Timestamp of the status transition. - `string sessionThreadID` Public sthr_ ID of the thread that is retrying. - `class BetaManagedAgentsSessionUpdatedEvent` - `"session.updated" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when the update was applied. - `?BetaManagedAgentsSessionAgent agent` 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. - `?BetaManagedAgentsBudgetLimit budget` 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. - `?array metadata` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `?string title` The session's new title. Present only when the update changed it. - `class BetaManagedAgentsStartEvent` - `"event_start" type` - `BetaManagedAgentsStartEventPreview event` 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. - `class BetaManagedAgentsDeltaEvent` - `"event_delta" type` - `BetaManagedAgentsDeltaContent delta` 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. - `string eventID` The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview. - `class BetaManagedAgentsSystemMessageEvent` - `"system.message" type` - `string id` Unique identifier for this event. - `list content` System content blocks. Text-only. - `?\Datetime processedAt` Timestamp when this system message was processed. - `class BetaManagedAgentsSessionUsageEvent` - `"session.usage" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when the snapshot was taken. - `ManagedAgentsSessionUsageSnapshot usage` The session's cumulative usage at the snapshot time. - `?BetaManagedAgentsBudgetLimit budget` The session's configured budget at the snapshot time, or null when the session has no budget. - `class ManagedAgentsWorkflowRunCreatedEvent` - `"workflow_run.created" type` - `string id` Unique identifier for this event. - `?string description` Description that the agent gave the run, passed on as written, or `null` if it gave none. - `string name` Name that the agent gave the run, passed on as written, or a name that the server assigned. - `list phases` The phases that the run's plan declares, in the plan's order. Can be empty. - `\Datetime processedAt` Timestamp when this event was processed. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `class ManagedAgentsWorkflowRunStatusEndedEvent` - `"workflow_run.status_ended" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this event was processed. - `ManagedAgentsWorkflowRunResult result` How the run ended. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `class ManagedAgentsWorkflowRunPhaseStartedEvent` - `"workflow_run.phase_started" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this event was processed. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `string workflowRunPhaseID` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `class ManagedAgentsWorkflowRunPhaseEndedEvent` - `"workflow_run.phase_ended" type` - `string id` Unique identifier for this event. - `string phaseStartedID` Identifier of the `workflow_run.phase_started` event that opened the phase. - `\Datetime processedAt` Timestamp when this event was processed. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `string workflowRunPhaseID` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `class ManagedAgentsWorkflowRunStatusRunningEvent` - `"workflow_run.status_running" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this event was processed. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `class ManagedAgentsWorkflowRunStatusIdleEvent` - `"workflow_run.status_idle" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this event was processed. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `class ManagedAgentsWorkflowRunErrorEvent` - `"workflow_run.error" type` - `string id` Unique identifier for this event. - `ManagedAgentsWorkflowRunError error` Why the run did not finish, or was not created. - `\Datetime processedAt` Timestamp when this event was processed. - `?string workflowRunID` Identifier of the run that met the error, or `null` when the error kept a run from being created. #### Example ```php beta ->sessions ->events ->streamStream( 'sesn_011CZkZAtmR3yMPDzynEDxu7', eventDeltas: [BetaManagedAgentsDeltaType::AGENT_MESSAGE], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsStreamSessionEvents); ``` ##### 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 `$client->beta->sessions->resources->add(string sessionID, string fileID, "file" type, ?string mountPath, ?list betas, ?string workspaceID): ManagedAgentsFileResource` **POST** `/v1/sessions/{session_id}/resources` Add Session Resource #### Parameters - `sessionID: string` (path parameter) - `fileID: string` ID of a previously uploaded file. - `type: "file"` - `mountPath?: optional string` Mount path in the container. Defaults to `/mnt/session/uploads/`. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsFileResource` - `"file" type` - `string id` - `\Datetime createdAt` A timestamp in RFC 3339 format - `string fileID` - `string mountPath` - `\Datetime updatedAt` A timestamp in RFC 3339 format #### Example ```php beta->sessions->resources->add( 'sesn_011CZkZAtmR3yMPDzynEDxu7', fileID: 'file_011CNha8iCJcU1wXNR6q4V8w', type: 'file', mountPath: '/uploads/receipt.pdf', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsFileResource); ``` ##### 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 `$client->beta->sessions->resources->list(string sessionID, ?int limit, ?string page, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/sessions/{session_id}/resources` List Session Resources #### Parameters - `sessionID: string` (path parameter) - `limit?: optional int` (query parameter) Maximum number of resources to return per page (max 1000). If omitted, returns all resources. - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsSessionResource` - `class ManagedAgentsGitHubRepositoryResource` - `"github_repository" type` - `string id` - `\Datetime createdAt` A timestamp in RFC 3339 format - `string mountPath` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `string url` - `?Checkout checkout` - `class ManagedAgentsFileResource` - `"file" type` - `string id` - `\Datetime createdAt` A timestamp in RFC 3339 format - `string fileID` - `string mountPath` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `class ManagedAgentsMemoryStoreResource` - `"memory_store" type` - `string memoryStoreID` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `?Access access` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `?string description` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `?string instructions` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `?string mountPath` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `?string name` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. #### Example ```php beta->sessions->resources->list( 'sesn_011CZkZAtmR3yMPDzynEDxu7', limit: 0, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->sessions->resources->retrieve(string resourceID, string sessionID, ?list betas, ?string workspaceID): ResourceGetResponse` **GET** `/v1/sessions/{session_id}/resources/{resource_id}` Get Session Resource #### Parameters - `sessionID: string` (path parameter) - `resourceID: string` (path parameter) - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ResourceGetResponse` - `class ManagedAgentsGitHubRepositoryResource` - `"github_repository" type` - `string id` - `\Datetime createdAt` A timestamp in RFC 3339 format - `string mountPath` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `string url` - `?Checkout checkout` - `class ManagedAgentsFileResource` - `"file" type` - `string id` - `\Datetime createdAt` A timestamp in RFC 3339 format - `string fileID` - `string mountPath` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `class ManagedAgentsMemoryStoreResource` - `"memory_store" type` - `string memoryStoreID` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `?Access access` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `?string description` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `?string instructions` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `?string mountPath` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `?string name` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. #### Example ```php beta->sessions->resources->retrieve( 'sesrsc_011CZkZBJq5dWxk9fVLNcPht', sessionID: 'sesn_011CZkZAtmR3yMPDzynEDxu7', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($resource); ``` ##### 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 `$client->beta->sessions->resources->update(string resourceID, string sessionID, string authorizationToken, ?list betas, ?string workspaceID): ResourceUpdateResponse` **POST** `/v1/sessions/{session_id}/resources/{resource_id}` Update Session Resource #### Parameters - `sessionID: string` (path parameter) - `resourceID: string` (path parameter) - `authorizationToken: string` New authorization token for the resource. Currently only `github_repository` resources support token rotation. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ResourceUpdateResponse` - `class ManagedAgentsGitHubRepositoryResource` - `"github_repository" type` - `string id` - `\Datetime createdAt` A timestamp in RFC 3339 format - `string mountPath` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `string url` - `?Checkout checkout` - `class ManagedAgentsFileResource` - `"file" type` - `string id` - `\Datetime createdAt` A timestamp in RFC 3339 format - `string fileID` - `string mountPath` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `class ManagedAgentsMemoryStoreResource` - `"memory_store" type` - `string memoryStoreID` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `?Access access` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `?string description` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `?string instructions` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `?string mountPath` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `?string name` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. #### Example ```php beta->sessions->resources->update( 'sesrsc_011CZkZBJq5dWxk9fVLNcPht', sessionID: 'sesn_011CZkZAtmR3yMPDzynEDxu7', authorizationToken: 'ghp_exampletoken', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($resource); ``` ##### 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 `$client->beta->sessions->resources->delete(string resourceID, string sessionID, ?list betas, ?string workspaceID): ManagedAgentsDeleteSessionResource` **DELETE** `/v1/sessions/{session_id}/resources/{resource_id}` Delete Session Resource #### Parameters - `sessionID: string` (path parameter) - `resourceID: string` (path parameter) - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsDeleteSessionResource` - `"session_resource_deleted" type` - `string id` #### Example ```php beta ->sessions ->resources ->delete( 'sesrsc_011CZkZBJq5dWxk9fVLNcPht', sessionID: 'sesn_011CZkZAtmR3yMPDzynEDxu7', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsDeleteSessionResource); ``` ##### Response (200) ```json { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "type": "session_resource_deleted" } ``` ## Beta › Sessions › Threads ### List Session Threads `$client->beta->sessions->threads->list(string sessionID, ?int limit, ?string page, ?list statuses, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/sessions/{session_id}/threads` List Session Threads #### Parameters - `sessionID: string` (path parameter) - `limit?: optional int` (query parameter) Maximum results per page. Defaults to 1000. - `page?: optional string` (query parameter) Opaque pagination cursor from a previous response's `next_page`. Forward-only. - `statuses?: optional list` (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. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsSessionThread` - `"session_thread" type` - `string id` Unique identifier for this thread. - `Agent agent` Resolved agent definition for this thread. Snapshot of the agent at thread creation time. - `?\Datetime archivedAt` When the thread was archived. Null if not archived. - `\Datetime createdAt` When the thread was created. - `?string parentThreadID` Parent thread that spawned this thread. Null for the primary thread. - `string sessionID` The session this thread belongs to. - `?ManagedAgentsSessionThreadStats stats` Timing statistics for this thread. Null until the thread's first status transition. - `ManagedAgentsSessionThreadStatus status` Current execution status of the thread. - `\Datetime updatedAt` When the thread was last updated. - `?ManagedAgentsSessionThreadUsage usage` Cumulative token usage for this thread. Null until the thread's first idle transition. - `?string workflowRunID` Identifier of the workflow run that created the thread, or `null` for any other thread. #### Example ```php beta->sessions->threads->list( 'sesn_011CZkZAtmR3yMPDzynEDxu7', limit: 0, page: 'page', statuses: [ManagedAgentsSessionThreadStatus::RUNNING], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->sessions->threads->retrieve(string threadID, string sessionID, ?list betas, ?string workspaceID): ManagedAgentsSessionThread` **GET** `/v1/sessions/{session_id}/threads/{thread_id}` Get Session Thread #### Parameters - `sessionID: string` (path parameter) - `threadID: string` (path parameter) - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsSessionThread` - `"session_thread" type` - `string id` Unique identifier for this thread. - `Agent agent` Resolved agent definition for this thread. Snapshot of the agent at thread creation time. - `?\Datetime archivedAt` When the thread was archived. Null if not archived. - `\Datetime createdAt` When the thread was created. - `?string parentThreadID` Parent thread that spawned this thread. Null for the primary thread. - `string sessionID` The session this thread belongs to. - `?ManagedAgentsSessionThreadStats stats` Timing statistics for this thread. Null until the thread's first status transition. - `ManagedAgentsSessionThreadStatus status` Current execution status of the thread. - `\Datetime updatedAt` When the thread was last updated. - `?ManagedAgentsSessionThreadUsage usage` Cumulative token usage for this thread. Null until the thread's first idle transition. - `?string workflowRunID` Identifier of the workflow run that created the thread, or `null` for any other thread. #### Example ```php beta->sessions->threads->retrieve( 'sthr_011CZkZVWa6oJjw1rgXZpnBt', sessionID: 'sesn_011CZkZAtmR3yMPDzynEDxu7', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsSessionThread); ``` ##### 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 `$client->beta->sessions->threads->archive(string threadID, string sessionID, ?list betas, ?string workspaceID): ManagedAgentsSessionThread` **POST** `/v1/sessions/{session_id}/threads/{thread_id}/archive` Archive Session Thread #### Parameters - `sessionID: string` (path parameter) - `threadID: string` (path parameter) - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsSessionThread` - `"session_thread" type` - `string id` Unique identifier for this thread. - `Agent agent` Resolved agent definition for this thread. Snapshot of the agent at thread creation time. - `?\Datetime archivedAt` When the thread was archived. Null if not archived. - `\Datetime createdAt` When the thread was created. - `?string parentThreadID` Parent thread that spawned this thread. Null for the primary thread. - `string sessionID` The session this thread belongs to. - `?ManagedAgentsSessionThreadStats stats` Timing statistics for this thread. Null until the thread's first status transition. - `ManagedAgentsSessionThreadStatus status` Current execution status of the thread. - `\Datetime updatedAt` When the thread was last updated. - `?ManagedAgentsSessionThreadUsage usage` Cumulative token usage for this thread. Null until the thread's first idle transition. - `?string workflowRunID` Identifier of the workflow run that created the thread, or `null` for any other thread. #### Example ```php beta->sessions->threads->archive( 'sthr_011CZkZVWa6oJjw1rgXZpnBt', sessionID: 'sesn_011CZkZAtmR3yMPDzynEDxu7', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsSessionThread); ``` ##### 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 `$client->beta->sessions->threads->events->list(string threadID, string sessionID, ?int limit, ?string page, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/sessions/{session_id}/threads/{thread_id}/events` List Session Thread Events #### Parameters - `sessionID: string` (path parameter) - `threadID: string` (path parameter) - `limit?: optional int` (query parameter) - `page?: optional string` (query parameter) - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsSessionEvent` - `class ManagedAgentsUserMessageEvent` - `"user.message" type` - `string id` Unique identifier for this event. - `list content` Array of content blocks comprising the user message. - `?\Datetime processedAt` Timestamp when the agent finished processing this message. - `class ManagedAgentsUserInterruptEvent` - `"user.interrupt" type` - `string id` Unique identifier for this event. - `?\Datetime processedAt` Timestamp when the interrupt was processed. - `?string sessionThreadID` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `class ManagedAgentsUserToolConfirmationEvent` - `"user.tool_confirmation" type` - `string id` Unique identifier for this event. - `Result result` The confirmation result: 'allow' or 'deny'. - `string toolUseID` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=php#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `?string denyMessage` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `?\Datetime processedAt` Timestamp when the confirmation was processed. - `?string sessionThreadID` Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread. - `class ManagedAgentsUserCustomToolResultEvent` - `"user.custom_tool_result" type` - `string id` Unique identifier for this event. - `string customToolUseID` 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=php#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` Timestamp when this result was processed. - `?string sessionThreadID` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `class ManagedAgentsAgentCustomToolUseEvent` - `"agent.custom_tool_use" type` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the custom tool being called. - `\Datetime processedAt` Timestamp when this tool use was processed. - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.custom_tool_result` by `custom_tool_use_id`, so clients do not send it back. - `class ManagedAgentsAgentMessageEvent` - `"agent.message" type` - `string id` Unique identifier for this event. - `list content` Array of text blocks comprising the agent response. - `\Datetime processedAt` Timestamp when this response was generated. - `class ManagedAgentsAgentThinkingEvent` - `"agent.thinking" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this thinking was produced. - `class ManagedAgentsAgentMCPToolUseEvent` - `"agent.mcp_tool_use" type` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string mcpServerName` Name of the MCP server providing the tool. - `string name` Name of the MCP tool being used. - `\Datetime processedAt` Timestamp when this event was processed. - `?ManagedAgentsAgentEvaluatedPermission evaluatedPermission` The evaluated permission policy for this tool invocation. - `?ManagedAgentsAgentToolEvaluation evaluation` 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). - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.tool_confirmation` by `tool_use_id`, so clients do not send it back. - `class ManagedAgentsAgentMCPToolResultEvent` - `"agent.mcp_tool_result" type` - `string id` Unique identifier for this event. - `string mcpToolUseID` The id of the `agent.mcp_tool_use` event this result corresponds to. - `\Datetime processedAt` Timestamp when this event was processed. - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `class ManagedAgentsAgentToolUseEvent` - `"agent.tool_use" type` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the agent tool being used. - `\Datetime processedAt` Timestamp when this event was processed. - `?ManagedAgentsAgentEvaluatedPermission evaluatedPermission` The evaluated permission policy for this tool invocation. - `?ManagedAgentsAgentToolEvaluation evaluation` 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). - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. 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. - `class ManagedAgentsAgentToolResultEvent` - `"agent.tool_result" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this event was processed. - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to. - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `class ManagedAgentsAgentThreadMessageReceivedEvent` - `"agent.thread_message_received" type` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `string fromSessionThreadID` Public `sthr_` ID of the thread that sent the message. - `\Datetime processedAt` Timestamp when the message was received. - `?string fromAgentName` Name of the callable agent this message came from. Absent when received from the primary agent. - `class ManagedAgentsAgentThreadMessageSentEvent` - `"agent.thread_message_sent" type` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `\Datetime processedAt` Timestamp when the message was sent. - `string toSessionThreadID` Public `sthr_` ID of the thread the message was sent to. - `?string toAgentName` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `class ManagedAgentsAgentThreadContextCompactedEvent` - `"agent.thread_context_compacted" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when compaction was processed. - `class ManagedAgentsSessionErrorEvent` - `"session.error" type` - `string id` Unique identifier for this event. - `Error error` - `\Datetime processedAt` Timestamp when the error occurred. - `class ManagedAgentsSessionStatusRescheduledEvent` - `"session.status_rescheduled" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp of status change. - `class ManagedAgentsSessionStatusRunningEvent` - `"session.status_running" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp of status change. - `class ManagedAgentsSessionStatusIdleEvent` - `"session.status_idle" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp of status change. - `?ManagedAgentsSessionRefusalStopDetails stopDetails` Structured information about why the session stopped. `null` when there is nothing more to report. - `StopReason stopReason` - `class ManagedAgentsSessionStatusTerminatedEvent` - `"session.status_terminated" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp of status change. - `class ManagedAgentsSessionThreadCreatedEvent` - `"session.thread_created" type` - `string id` Unique identifier for this event. - `string agentName` Name of the callable agent the thread runs. - `\Datetime processedAt` Timestamp when the thread was created. - `string sessionThreadID` Public `sthr_` ID of the newly created thread. - `?string workflowRunID` Identifier of the workflow run that created the thread, or `null` for any other thread. - `class ManagedAgentsSpanOutcomeEvaluationStartEvent` - `"span.outcome_evaluation_start" type` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` Timestamp when outcome evaluation started. - `class ManagedAgentsSpanOutcomeEvaluationEndEvent` - `"span.outcome_evaluation_end" type` - `string id` Unique identifier for this event. - `string explanation` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeEvaluationStartID` The id of the corresponding `span.outcome_evaluation_start` event. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` Timestamp when outcome evaluation ended. - `string result` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `ManagedAgentsSpanModelUsage usage` Aggregate token usage for this evaluation cycle. Sums across all grader model requests within the cycle. - `class ManagedAgentsSpanModelRequestStartEvent` - `"span.model_request_start" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when the model request started. - `class ManagedAgentsSpanModelRequestEndEvent` - `"span.model_request_end" type` - `string id` Unique identifier for this event. - `?bool isError` Whether the model request resulted in an error. - `string modelRequestStartID` The id of the corresponding `span.model_request_start` event. - `ManagedAgentsSpanModelUsage modelUsage` Token usage for this model request. - `\Datetime processedAt` Timestamp when the model request completed. - `class ManagedAgentsSpanOutcomeEvaluationOngoingEvent` - `"span.outcome_evaluation_ongoing" type` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` Timestamp when this heartbeat was emitted. - `class ManagedAgentsUserDefineOutcomeEvent` - `"user.define_outcome" type` - `string id` Unique identifier for this event. - `string description` What the agent should produce. Copied from the input event. - `?int maxIterations` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `string outcomeID` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `\Datetime processedAt` Timestamp when the outcome was accepted. - `Rubric rubric` How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants. - `class ManagedAgentsSessionDeletedEvent` - `"session.deleted" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when the session was deleted. - `class ManagedAgentsSessionThreadStatusRunningEvent` - `"session.thread_status_running" type` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` Timestamp of the status transition. - `string sessionThreadID` Public sthr_ ID of the thread that started running. - `class ManagedAgentsSessionThreadStatusIdleEvent` - `"session.thread_status_idle" type` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` Timestamp of the status transition. - `string sessionThreadID` Public sthr_ ID of the thread that went idle. - `?ManagedAgentsSessionRefusalStopDetails stopDetails` Structured information about why the thread stopped. `null` when there is nothing more to report. - `StopReason stopReason` - `class ManagedAgentsSessionThreadStatusTerminatedEvent` - `"session.thread_status_terminated" type` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` Timestamp of the status transition. - `string sessionThreadID` Public sthr_ ID of the thread that terminated. - `class BetaManagedAgentsUserToolResultEvent` - `"user.tool_result" type` - `string id` Unique identifier for this event. - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=php#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` Timestamp when this result was processed. - `?string sessionThreadID` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `class ManagedAgentsSessionThreadStatusRescheduledEvent` - `"session.thread_status_rescheduled" type` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` Timestamp of the status transition. - `string sessionThreadID` Public sthr_ ID of the thread that is retrying. - `class BetaManagedAgentsSessionUpdatedEvent` - `"session.updated" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when the update was applied. - `?BetaManagedAgentsSessionAgent agent` 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. - `?BetaManagedAgentsBudgetLimit budget` 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. - `?array metadata` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `?string title` The session's new title. Present only when the update changed it. - `class BetaManagedAgentsSystemMessageEvent` - `"system.message" type` - `string id` Unique identifier for this event. - `list content` System content blocks. Text-only. - `?\Datetime processedAt` Timestamp when this system message was processed. - `class BetaManagedAgentsSessionUsageEvent` - `"session.usage" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when the snapshot was taken. - `ManagedAgentsSessionUsageSnapshot usage` The session's cumulative usage at the snapshot time. - `?BetaManagedAgentsBudgetLimit budget` The session's configured budget at the snapshot time, or null when the session has no budget. - `class ManagedAgentsWorkflowRunCreatedEvent` - `"workflow_run.created" type` - `string id` Unique identifier for this event. - `?string description` Description that the agent gave the run, passed on as written, or `null` if it gave none. - `string name` Name that the agent gave the run, passed on as written, or a name that the server assigned. - `list phases` The phases that the run's plan declares, in the plan's order. Can be empty. - `\Datetime processedAt` Timestamp when this event was processed. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `class ManagedAgentsWorkflowRunStatusEndedEvent` - `"workflow_run.status_ended" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this event was processed. - `ManagedAgentsWorkflowRunResult result` How the run ended. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `class ManagedAgentsWorkflowRunPhaseStartedEvent` - `"workflow_run.phase_started" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this event was processed. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `string workflowRunPhaseID` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `class ManagedAgentsWorkflowRunPhaseEndedEvent` - `"workflow_run.phase_ended" type` - `string id` Unique identifier for this event. - `string phaseStartedID` Identifier of the `workflow_run.phase_started` event that opened the phase. - `\Datetime processedAt` Timestamp when this event was processed. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `string workflowRunPhaseID` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `class ManagedAgentsWorkflowRunStatusRunningEvent` - `"workflow_run.status_running" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this event was processed. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `class ManagedAgentsWorkflowRunStatusIdleEvent` - `"workflow_run.status_idle" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this event was processed. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `class ManagedAgentsWorkflowRunErrorEvent` - `"workflow_run.error" type` - `string id` Unique identifier for this event. - `ManagedAgentsWorkflowRunError error` Why the run did not finish, or was not created. - `\Datetime processedAt` Timestamp when this event was processed. - `?string workflowRunID` Identifier of the run that met the error, or `null` when the error kept a run from being created. #### Example ```php beta->sessions->threads->events->list( 'sthr_011CZkZVWa6oJjw1rgXZpnBt', sessionID: 'sesn_011CZkZAtmR3yMPDzynEDxu7', limit: 0, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->sessions->threads->events->streamStream(string threadID, string sessionID, ?list eventDeltas, ?list betas, ?string workspaceID): BaseStream` **GET** `/v1/sessions/{session_id}/threads/{thread_id}/stream` Stream Session Thread Events #### Parameters - `sessionID: string` (path parameter) - `threadID: string` (path parameter) - `eventDeltas?: optional list` (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. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsStreamSessionThreadEvents` - `class ManagedAgentsUserMessageEvent` - `"user.message" type` - `string id` Unique identifier for this event. - `list content` Array of content blocks comprising the user message. - `?\Datetime processedAt` Timestamp when the agent finished processing this message. - `class ManagedAgentsUserInterruptEvent` - `"user.interrupt" type` - `string id` Unique identifier for this event. - `?\Datetime processedAt` Timestamp when the interrupt was processed. - `?string sessionThreadID` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `class ManagedAgentsUserToolConfirmationEvent` - `"user.tool_confirmation" type` - `string id` Unique identifier for this event. - `Result result` The confirmation result: 'allow' or 'deny'. - `string toolUseID` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=php#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `?string denyMessage` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `?\Datetime processedAt` Timestamp when the confirmation was processed. - `?string sessionThreadID` Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread. - `class ManagedAgentsUserCustomToolResultEvent` - `"user.custom_tool_result" type` - `string id` Unique identifier for this event. - `string customToolUseID` 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=php#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` Timestamp when this result was processed. - `?string sessionThreadID` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `class ManagedAgentsAgentCustomToolUseEvent` - `"agent.custom_tool_use" type` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the custom tool being called. - `\Datetime processedAt` Timestamp when this tool use was processed. - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.custom_tool_result` by `custom_tool_use_id`, so clients do not send it back. - `class ManagedAgentsAgentMessageEvent` - `"agent.message" type` - `string id` Unique identifier for this event. - `list content` Array of text blocks comprising the agent response. - `\Datetime processedAt` Timestamp when this response was generated. - `class ManagedAgentsAgentThinkingEvent` - `"agent.thinking" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this thinking was produced. - `class ManagedAgentsAgentMCPToolUseEvent` - `"agent.mcp_tool_use" type` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string mcpServerName` Name of the MCP server providing the tool. - `string name` Name of the MCP tool being used. - `\Datetime processedAt` Timestamp when this event was processed. - `?ManagedAgentsAgentEvaluatedPermission evaluatedPermission` The evaluated permission policy for this tool invocation. - `?ManagedAgentsAgentToolEvaluation evaluation` 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). - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.tool_confirmation` by `tool_use_id`, so clients do not send it back. - `class ManagedAgentsAgentMCPToolResultEvent` - `"agent.mcp_tool_result" type` - `string id` Unique identifier for this event. - `string mcpToolUseID` The id of the `agent.mcp_tool_use` event this result corresponds to. - `\Datetime processedAt` Timestamp when this event was processed. - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `class ManagedAgentsAgentToolUseEvent` - `"agent.tool_use" type` - `string id` Unique identifier for this event. - `array input` Input parameters for the tool call. - `string name` Name of the agent tool being used. - `\Datetime processedAt` Timestamp when this event was processed. - `?ManagedAgentsAgentEvaluatedPermission evaluatedPermission` The evaluated permission policy for this tool invocation. - `?ManagedAgentsAgentToolEvaluation evaluation` 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). - `?string sessionThreadID` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. 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. - `class ManagedAgentsAgentToolResultEvent` - `"agent.tool_result" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this event was processed. - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to. - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `class ManagedAgentsAgentThreadMessageReceivedEvent` - `"agent.thread_message_received" type` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `string fromSessionThreadID` Public `sthr_` ID of the thread that sent the message. - `\Datetime processedAt` Timestamp when the message was received. - `?string fromAgentName` Name of the callable agent this message came from. Absent when received from the primary agent. - `class ManagedAgentsAgentThreadMessageSentEvent` - `"agent.thread_message_sent" type` - `string id` Unique identifier for this event. - `list content` Message content blocks. - `\Datetime processedAt` Timestamp when the message was sent. - `string toSessionThreadID` Public `sthr_` ID of the thread the message was sent to. - `?string toAgentName` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `class ManagedAgentsAgentThreadContextCompactedEvent` - `"agent.thread_context_compacted" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when compaction was processed. - `class ManagedAgentsSessionErrorEvent` - `"session.error" type` - `string id` Unique identifier for this event. - `Error error` - `\Datetime processedAt` Timestamp when the error occurred. - `class ManagedAgentsSessionStatusRescheduledEvent` - `"session.status_rescheduled" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp of status change. - `class ManagedAgentsSessionStatusRunningEvent` - `"session.status_running" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp of status change. - `class ManagedAgentsSessionStatusIdleEvent` - `"session.status_idle" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp of status change. - `?ManagedAgentsSessionRefusalStopDetails stopDetails` Structured information about why the session stopped. `null` when there is nothing more to report. - `StopReason stopReason` - `class ManagedAgentsSessionStatusTerminatedEvent` - `"session.status_terminated" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp of status change. - `class ManagedAgentsSessionThreadCreatedEvent` - `"session.thread_created" type` - `string id` Unique identifier for this event. - `string agentName` Name of the callable agent the thread runs. - `\Datetime processedAt` Timestamp when the thread was created. - `string sessionThreadID` Public `sthr_` ID of the newly created thread. - `?string workflowRunID` Identifier of the workflow run that created the thread, or `null` for any other thread. - `class ManagedAgentsSpanOutcomeEvaluationStartEvent` - `"span.outcome_evaluation_start" type` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` Timestamp when outcome evaluation started. - `class ManagedAgentsSpanOutcomeEvaluationEndEvent` - `"span.outcome_evaluation_end" type` - `string id` Unique identifier for this event. - `string explanation` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeEvaluationStartID` The id of the corresponding `span.outcome_evaluation_start` event. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` Timestamp when outcome evaluation ended. - `string result` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `ManagedAgentsSpanModelUsage usage` Aggregate token usage for this evaluation cycle. Sums across all grader model requests within the cycle. - `class ManagedAgentsSpanModelRequestStartEvent` - `"span.model_request_start" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when the model request started. - `class ManagedAgentsSpanModelRequestEndEvent` - `"span.model_request_end" type` - `string id` Unique identifier for this event. - `?bool isError` Whether the model request resulted in an error. - `string modelRequestStartID` The id of the corresponding `span.model_request_start` event. - `ManagedAgentsSpanModelUsage modelUsage` Token usage for this model request. - `\Datetime processedAt` Timestamp when the model request completed. - `class ManagedAgentsSpanOutcomeEvaluationOngoingEvent` - `"span.outcome_evaluation_ongoing" type` - `string id` Unique identifier for this event. - `int iteration` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `string outcomeID` The `outc_` ID of the outcome being evaluated. - `\Datetime processedAt` Timestamp when this heartbeat was emitted. - `class ManagedAgentsUserDefineOutcomeEvent` - `"user.define_outcome" type` - `string id` Unique identifier for this event. - `string description` What the agent should produce. Copied from the input event. - `?int maxIterations` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `string outcomeID` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `\Datetime processedAt` Timestamp when the outcome was accepted. - `Rubric rubric` How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants. - `class ManagedAgentsSessionDeletedEvent` - `"session.deleted" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when the session was deleted. - `class ManagedAgentsSessionThreadStatusRunningEvent` - `"session.thread_status_running" type` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` Timestamp of the status transition. - `string sessionThreadID` Public sthr_ ID of the thread that started running. - `class ManagedAgentsSessionThreadStatusIdleEvent` - `"session.thread_status_idle" type` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` Timestamp of the status transition. - `string sessionThreadID` Public sthr_ ID of the thread that went idle. - `?ManagedAgentsSessionRefusalStopDetails stopDetails` Structured information about why the thread stopped. `null` when there is nothing more to report. - `StopReason stopReason` - `class ManagedAgentsSessionThreadStatusTerminatedEvent` - `"session.thread_status_terminated" type` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` Timestamp of the status transition. - `string sessionThreadID` Public sthr_ ID of the thread that terminated. - `class BetaManagedAgentsUserToolResultEvent` - `"user.tool_result" type` - `string id` Unique identifier for this event. - `string toolUseID` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=php#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `?list content` The result content returned by the tool. - `?bool isError` Whether the tool execution resulted in an error. - `?\Datetime processedAt` Timestamp when this result was processed. - `?string sessionThreadID` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `class ManagedAgentsSessionThreadStatusRescheduledEvent` - `"session.thread_status_rescheduled" type` - `string id` Unique identifier for this event. - `string agentName` Name of the agent the thread runs. - `\Datetime processedAt` Timestamp of the status transition. - `string sessionThreadID` Public sthr_ ID of the thread that is retrying. - `class BetaManagedAgentsSessionUpdatedEvent` - `"session.updated" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when the update was applied. - `?BetaManagedAgentsSessionAgent agent` 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. - `?BetaManagedAgentsBudgetLimit budget` 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. - `?array metadata` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `?string title` The session's new title. Present only when the update changed it. - `class BetaManagedAgentsStartEvent` - `"event_start" type` - `BetaManagedAgentsStartEventPreview event` 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. - `class BetaManagedAgentsDeltaEvent` - `"event_delta" type` - `BetaManagedAgentsDeltaContent delta` 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. - `string eventID` The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview. - `class BetaManagedAgentsSystemMessageEvent` - `"system.message" type` - `string id` Unique identifier for this event. - `list content` System content blocks. Text-only. - `?\Datetime processedAt` Timestamp when this system message was processed. - `class BetaManagedAgentsSessionUsageEvent` - `"session.usage" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when the snapshot was taken. - `ManagedAgentsSessionUsageSnapshot usage` The session's cumulative usage at the snapshot time. - `?BetaManagedAgentsBudgetLimit budget` The session's configured budget at the snapshot time, or null when the session has no budget. - `class ManagedAgentsWorkflowRunCreatedEvent` - `"workflow_run.created" type` - `string id` Unique identifier for this event. - `?string description` Description that the agent gave the run, passed on as written, or `null` if it gave none. - `string name` Name that the agent gave the run, passed on as written, or a name that the server assigned. - `list phases` The phases that the run's plan declares, in the plan's order. Can be empty. - `\Datetime processedAt` Timestamp when this event was processed. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `class ManagedAgentsWorkflowRunStatusEndedEvent` - `"workflow_run.status_ended" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this event was processed. - `ManagedAgentsWorkflowRunResult result` How the run ended. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `class ManagedAgentsWorkflowRunPhaseStartedEvent` - `"workflow_run.phase_started" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this event was processed. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `string workflowRunPhaseID` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `class ManagedAgentsWorkflowRunPhaseEndedEvent` - `"workflow_run.phase_ended" type` - `string id` Unique identifier for this event. - `string phaseStartedID` Identifier of the `workflow_run.phase_started` event that opened the phase. - `\Datetime processedAt` Timestamp when this event was processed. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `string workflowRunPhaseID` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `class ManagedAgentsWorkflowRunStatusRunningEvent` - `"workflow_run.status_running" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this event was processed. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `class ManagedAgentsWorkflowRunStatusIdleEvent` - `"workflow_run.status_idle" type` - `string id` Unique identifier for this event. - `\Datetime processedAt` Timestamp when this event was processed. - `string workflowRunID` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `class ManagedAgentsWorkflowRunErrorEvent` - `"workflow_run.error" type` - `string id` Unique identifier for this event. - `ManagedAgentsWorkflowRunError error` Why the run did not finish, or was not created. - `\Datetime processedAt` Timestamp when this event was processed. - `?string workflowRunID` Identifier of the run that met the error, or `null` when the error kept a run from being created. #### Example ```php beta ->sessions ->threads ->events ->streamStream( 'sthr_011CZkZVWa6oJjw1rgXZpnBt', sessionID: 'sesn_011CZkZAtmR3yMPDzynEDxu7', eventDeltas: [BetaManagedAgentsDeltaType::AGENT_MESSAGE], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsStreamSessionThreadEvents); ``` ##### 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 `$client->beta->deployments->create(Agent agent, string environmentID, list initialEvents, string name, ?BetaManagedAgentsBudgetLimit budget, ?string description, ?array metadata, ?list resources, ?BetaManagedAgentsScheduleParams schedule, ?list vaultIDs, ?list betas, ?string workspaceID): BetaManagedAgentsDeployment` **POST** `/v1/deployments` Create Deployment #### Parameters - `agent: Agent` Agent to deploy. Accepts the `agent` ID string, which pins the latest version, or an `agent` object with both id and version specified. The agent must exist and not be archived. - `environmentID: string` ID of the `environment` defining the container configuration for sessions created from this deployment. - `initialEvents: list` Events to send to each session immediately after creation. At least 1, maximum 50. - `name: string` Human-readable name for the deployment. - `budget?: optional BetaManagedAgentsBudgetLimit` 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. - `metadata?: optional array` Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `resources?: optional list` Resources (e.g. repositories, files) to mount into each session's container. Maximum 500. - `schedule?: optional BetaManagedAgentsScheduleParams` Optional recurring cron schedule. When present, the deployment fires automatically. Both expression and timezone are required when schedule is set. - `vaultIDs?: optional list` Vault IDs for stored credentials the agent can use during sessions created from this deployment. Maximum 50. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsDeployment` - `"deployment" type` - `string id` Unique identifier for this deployment. - `BetaManagedAgentsAgentReference agent` Reference to the agent this deployment runs, resolved to a concrete version. - `?\Datetime archivedAt` Time the deployment was archived. Null if not archived. - `\Datetime createdAt` Time the deployment was created. - `?string description` Description of what the deployment does. - `string environmentID` ID of the `environment` where sessions run. - `list initialEvents` Events sent to each session immediately after creation. - `array metadata` Arbitrary key-value metadata. Maximum 16 pairs. - `string name` Human-readable name. - `?BetaManagedAgentsDeploymentPausedReason pausedReason` Why the deployment is `paused`. Non-null exactly when `status` is `paused`; null otherwise. - `list resources` Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. - `?BetaManagedAgentsSchedule schedule` Recurring cron schedule. Presence enables scheduled execution; null means manual-only. Includes computed timestamps (next fire times, last run) on the cron variant. - `BetaManagedAgentsDeploymentStatus status` Computed status of the deployment: `active` or `paused`. Archived deployments report `active` with `archived_at` set. - `\Datetime updatedAt` Time the deployment was last updated. - `list vaultIDs` Vault IDs supplying stored credentials for sessions created from this deployment. - `?BetaManagedAgentsBudgetLimit budget` Spend ceiling stamped onto each session created from this deployment. Absent when no budget is set. #### Example ```php beta->deployments->create( agent: 'string', environmentID: 'x', initialEvents: [ [ 'content' => [['text' => 'Where is my order #1234?', 'type' => 'text']], 'type' => 'user.message', ], ], name: 'x', budget: [ 'maxListCost' => ['amount' => '2500', 'currency' => BetaCurrency::USD], 'type' => 'limit', ], description: 'description', metadata: ['foo' => 'string'], resources: [ [ 'fileID' => 'file_011CNha8iCJcU1wXNR6q4V8w', 'type' => 'file', 'mountPath' => '/uploads/receipt.pdf', ], ], schedule: [ 'expression' => '0 9 * * 1-5', 'timezone' => 'America/Los_Angeles', 'type' => 'cron', ], vaultIDs: ['string'], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsDeployment); ``` ##### 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 `$client->beta->deployments->list(?string agentID, ?\Datetime createdAtGte, ?\Datetime createdAtLte, ?bool includeArchived, ?int limit, ?string page, ?BetaManagedAgentsDeploymentStatus status, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/deployments` List Deployments #### Parameters - `agentID?: optional string` (query parameter) Filter by agent ID. - `createdAtGte?: optional \Datetime` (query parameter) Return deployments created at or after this time (inclusive). - `createdAtLte?: optional \Datetime` (query parameter) Return deployments created at or before this time (inclusive). - `includeArchived?: optional bool` (query parameter) When true, includes archived deployments. Default: false (exclude archived). - `limit?: optional int` (query parameter) Maximum results per page. Default 20, maximum 100. - `page?: optional string` (query parameter) Opaque pagination cursor. - `status?: optional BetaManagedAgentsDeploymentStatus` (query parameter) Filter by status: `active` or `paused`. Omit for both. To include archived deployments, use `include_archived` instead; the two cannot be combined. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsDeployment` - `"deployment" type` - `string id` Unique identifier for this deployment. - `BetaManagedAgentsAgentReference agent` Reference to the agent this deployment runs, resolved to a concrete version. - `?\Datetime archivedAt` Time the deployment was archived. Null if not archived. - `\Datetime createdAt` Time the deployment was created. - `?string description` Description of what the deployment does. - `string environmentID` ID of the `environment` where sessions run. - `list initialEvents` Events sent to each session immediately after creation. - `array metadata` Arbitrary key-value metadata. Maximum 16 pairs. - `string name` Human-readable name. - `?BetaManagedAgentsDeploymentPausedReason pausedReason` Why the deployment is `paused`. Non-null exactly when `status` is `paused`; null otherwise. - `list resources` Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. - `?BetaManagedAgentsSchedule schedule` Recurring cron schedule. Presence enables scheduled execution; null means manual-only. Includes computed timestamps (next fire times, last run) on the cron variant. - `BetaManagedAgentsDeploymentStatus status` Computed status of the deployment: `active` or `paused`. Archived deployments report `active` with `archived_at` set. - `\Datetime updatedAt` Time the deployment was last updated. - `list vaultIDs` Vault IDs supplying stored credentials for sessions created from this deployment. - `?BetaManagedAgentsBudgetLimit budget` Spend ceiling stamped onto each session created from this deployment. Absent when no budget is set. #### Example ```php beta->deployments->list( agentID: 'agent_id', createdAtGte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtLte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), includeArchived: true, limit: 0, page: 'page', status: BetaManagedAgentsDeploymentStatus::ACTIVE, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->deployments->retrieve(string deploymentID, ?list betas, ?string workspaceID): BetaManagedAgentsDeployment` **GET** `/v1/deployments/{deployment_id}` Get Deployment #### Parameters - `deploymentID: string` (path parameter) Unique identifier of the deployment. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsDeployment` - `"deployment" type` - `string id` Unique identifier for this deployment. - `BetaManagedAgentsAgentReference agent` Reference to the agent this deployment runs, resolved to a concrete version. - `?\Datetime archivedAt` Time the deployment was archived. Null if not archived. - `\Datetime createdAt` Time the deployment was created. - `?string description` Description of what the deployment does. - `string environmentID` ID of the `environment` where sessions run. - `list initialEvents` Events sent to each session immediately after creation. - `array metadata` Arbitrary key-value metadata. Maximum 16 pairs. - `string name` Human-readable name. - `?BetaManagedAgentsDeploymentPausedReason pausedReason` Why the deployment is `paused`. Non-null exactly when `status` is `paused`; null otherwise. - `list resources` Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. - `?BetaManagedAgentsSchedule schedule` Recurring cron schedule. Presence enables scheduled execution; null means manual-only. Includes computed timestamps (next fire times, last run) on the cron variant. - `BetaManagedAgentsDeploymentStatus status` Computed status of the deployment: `active` or `paused`. Archived deployments report `active` with `archived_at` set. - `\Datetime updatedAt` Time the deployment was last updated. - `list vaultIDs` Vault IDs supplying stored credentials for sessions created from this deployment. - `?BetaManagedAgentsBudgetLimit budget` Spend ceiling stamped onto each session created from this deployment. Absent when no budget is set. #### Example ```php beta->deployments->retrieve( 'depl_011CZkZcDH3vPqd7xnEfwTai', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsDeployment); ``` ##### 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 `$client->beta->deployments->update(string deploymentID, ?Agent agent, ?BetaManagedAgentsBudgetLimit budget, ?string description, ?string environmentID, ?list initialEvents, ?array metadata, ?string name, ?list resources, ?BetaManagedAgentsScheduleParams schedule, ?list vaultIDs, ?list betas, ?string workspaceID): BetaManagedAgentsDeployment` **POST** `/v1/deployments/{deployment_id}` Update Deployment #### Parameters - `deploymentID: string` (path parameter) Unique identifier of the deployment to update. - `agent?: optional Agent` Agent to deploy. Accepts the `agent` ID string, which re-pins to the latest version, or an `agent` object with both id and version specified. Omit to preserve. Cannot be cleared. - `budget?: optional BetaManagedAgentsBudgetLimit` 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. - `environmentID?: optional string` ID of the `environment` where sessions run. Omit to preserve. Cannot be cleared. - `initialEvents?: optional list` Initial events. Full replacement. Omit to preserve. Cannot be cleared. At least 1, maximum 50. - `metadata?: optional array` 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. - `resources?: optional list` Session resources. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 500. - `schedule?: optional BetaManagedAgentsScheduleParams` Cron schedule. Full replacement. Omit to preserve; send null to clear (revert to manual-only). - `vaultIDs?: optional list` Vault IDs. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 50. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsDeployment` - `"deployment" type` - `string id` Unique identifier for this deployment. - `BetaManagedAgentsAgentReference agent` Reference to the agent this deployment runs, resolved to a concrete version. - `?\Datetime archivedAt` Time the deployment was archived. Null if not archived. - `\Datetime createdAt` Time the deployment was created. - `?string description` Description of what the deployment does. - `string environmentID` ID of the `environment` where sessions run. - `list initialEvents` Events sent to each session immediately after creation. - `array metadata` Arbitrary key-value metadata. Maximum 16 pairs. - `string name` Human-readable name. - `?BetaManagedAgentsDeploymentPausedReason pausedReason` Why the deployment is `paused`. Non-null exactly when `status` is `paused`; null otherwise. - `list resources` Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. - `?BetaManagedAgentsSchedule schedule` Recurring cron schedule. Presence enables scheduled execution; null means manual-only. Includes computed timestamps (next fire times, last run) on the cron variant. - `BetaManagedAgentsDeploymentStatus status` Computed status of the deployment: `active` or `paused`. Archived deployments report `active` with `archived_at` set. - `\Datetime updatedAt` Time the deployment was last updated. - `list vaultIDs` Vault IDs supplying stored credentials for sessions created from this deployment. - `?BetaManagedAgentsBudgetLimit budget` Spend ceiling stamped onto each session created from this deployment. Absent when no budget is set. #### Example ```php beta->deployments->update( 'depl_011CZkZcDH3vPqd7xnEfwTai', agent: 'string', budget: [ 'maxListCost' => ['amount' => '2500', 'currency' => BetaCurrency::USD], 'type' => 'limit', ], description: 'description', environmentID: 'environment_id', initialEvents: [ [ 'content' => [['text' => 'Where is my order #1234?', 'type' => 'text']], 'type' => 'user.message', ], ], metadata: ['foo' => 'string'], name: 'name', resources: [ [ 'fileID' => 'file_011CNha8iCJcU1wXNR6q4V8w', 'type' => 'file', 'mountPath' => '/uploads/receipt.pdf', ], ], schedule: [ 'expression' => '0 9 * * 1-5', 'timezone' => 'America/Los_Angeles', 'type' => 'cron', ], vaultIDs: ['string'], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsDeployment); ``` ##### 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 `$client->beta->deployments->archive(string deploymentID, ?list betas, ?string workspaceID): BetaManagedAgentsDeployment` **POST** `/v1/deployments/{deployment_id}/archive` Archive Deployment #### Parameters - `deploymentID: string` (path parameter) Unique identifier of the deployment to archive. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsDeployment` - `"deployment" type` - `string id` Unique identifier for this deployment. - `BetaManagedAgentsAgentReference agent` Reference to the agent this deployment runs, resolved to a concrete version. - `?\Datetime archivedAt` Time the deployment was archived. Null if not archived. - `\Datetime createdAt` Time the deployment was created. - `?string description` Description of what the deployment does. - `string environmentID` ID of the `environment` where sessions run. - `list initialEvents` Events sent to each session immediately after creation. - `array metadata` Arbitrary key-value metadata. Maximum 16 pairs. - `string name` Human-readable name. - `?BetaManagedAgentsDeploymentPausedReason pausedReason` Why the deployment is `paused`. Non-null exactly when `status` is `paused`; null otherwise. - `list resources` Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. - `?BetaManagedAgentsSchedule schedule` Recurring cron schedule. Presence enables scheduled execution; null means manual-only. Includes computed timestamps (next fire times, last run) on the cron variant. - `BetaManagedAgentsDeploymentStatus status` Computed status of the deployment: `active` or `paused`. Archived deployments report `active` with `archived_at` set. - `\Datetime updatedAt` Time the deployment was last updated. - `list vaultIDs` Vault IDs supplying stored credentials for sessions created from this deployment. - `?BetaManagedAgentsBudgetLimit budget` Spend ceiling stamped onto each session created from this deployment. Absent when no budget is set. #### Example ```php beta->deployments->archive( 'depl_011CZkZcDH3vPqd7xnEfwTai', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsDeployment); ``` ##### 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 `$client->beta->deployments->run(string deploymentID, ?list betas, ?string workspaceID): BetaManagedAgentsDeploymentRun` **POST** `/v1/deployments/{deployment_id}/run` Run Deployment Now #### Parameters - `deploymentID: string` (path parameter) Unique identifier of the deployment to run. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsDeploymentRun` - `"deployment_run" type` - `string id` Unique identifier for this run (`drun_...`). - `BetaManagedAgentsAgentReference agent` Snapshot of the agent at fire time. Always fully resolved — deployments pin agent + version. - `\Datetime createdAt` Time this run record was persisted. - `string deploymentID` ID of the deployment that produced this run. - `?Error error` Populated on creation failure. Null on success. Exactly one of `session_id` or `error` is non-null. - `?string sessionID` Populated on success. Null on creation failure. Exactly one of `session_id` or `error` is non-null. - `BetaManagedAgentsTriggerContext triggerContext` What triggered this run and trigger-specific metadata. #### Example ```php beta->deployments->run( 'depl_011CZkZcDH3vPqd7xnEfwTai', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsDeploymentRun); ``` ##### 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 `$client->beta->deployments->pause(string deploymentID, ?list betas, ?string workspaceID): BetaManagedAgentsDeployment` **POST** `/v1/deployments/{deployment_id}/pause` Pause Deployment #### Parameters - `deploymentID: string` (path parameter) Unique identifier of the deployment to pause. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsDeployment` - `"deployment" type` - `string id` Unique identifier for this deployment. - `BetaManagedAgentsAgentReference agent` Reference to the agent this deployment runs, resolved to a concrete version. - `?\Datetime archivedAt` Time the deployment was archived. Null if not archived. - `\Datetime createdAt` Time the deployment was created. - `?string description` Description of what the deployment does. - `string environmentID` ID of the `environment` where sessions run. - `list initialEvents` Events sent to each session immediately after creation. - `array metadata` Arbitrary key-value metadata. Maximum 16 pairs. - `string name` Human-readable name. - `?BetaManagedAgentsDeploymentPausedReason pausedReason` Why the deployment is `paused`. Non-null exactly when `status` is `paused`; null otherwise. - `list resources` Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. - `?BetaManagedAgentsSchedule schedule` Recurring cron schedule. Presence enables scheduled execution; null means manual-only. Includes computed timestamps (next fire times, last run) on the cron variant. - `BetaManagedAgentsDeploymentStatus status` Computed status of the deployment: `active` or `paused`. Archived deployments report `active` with `archived_at` set. - `\Datetime updatedAt` Time the deployment was last updated. - `list vaultIDs` Vault IDs supplying stored credentials for sessions created from this deployment. - `?BetaManagedAgentsBudgetLimit budget` Spend ceiling stamped onto each session created from this deployment. Absent when no budget is set. #### Example ```php beta->deployments->pause( 'depl_011CZkZcDH3vPqd7xnEfwTai', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsDeployment); ``` ##### 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 `$client->beta->deployments->unpause(string deploymentID, ?list betas, ?string workspaceID): BetaManagedAgentsDeployment` **POST** `/v1/deployments/{deployment_id}/unpause` Unpause Deployment #### Parameters - `deploymentID: string` (path parameter) Unique identifier of the deployment to unpause. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsDeployment` - `"deployment" type` - `string id` Unique identifier for this deployment. - `BetaManagedAgentsAgentReference agent` Reference to the agent this deployment runs, resolved to a concrete version. - `?\Datetime archivedAt` Time the deployment was archived. Null if not archived. - `\Datetime createdAt` Time the deployment was created. - `?string description` Description of what the deployment does. - `string environmentID` ID of the `environment` where sessions run. - `list initialEvents` Events sent to each session immediately after creation. - `array metadata` Arbitrary key-value metadata. Maximum 16 pairs. - `string name` Human-readable name. - `?BetaManagedAgentsDeploymentPausedReason pausedReason` Why the deployment is `paused`. Non-null exactly when `status` is `paused`; null otherwise. - `list resources` Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. - `?BetaManagedAgentsSchedule schedule` Recurring cron schedule. Presence enables scheduled execution; null means manual-only. Includes computed timestamps (next fire times, last run) on the cron variant. - `BetaManagedAgentsDeploymentStatus status` Computed status of the deployment: `active` or `paused`. Archived deployments report `active` with `archived_at` set. - `\Datetime updatedAt` Time the deployment was last updated. - `list vaultIDs` Vault IDs supplying stored credentials for sessions created from this deployment. - `?BetaManagedAgentsBudgetLimit budget` Spend ceiling stamped onto each session created from this deployment. Absent when no budget is set. #### Example ```php beta->deployments->unpause( 'depl_011CZkZcDH3vPqd7xnEfwTai', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsDeployment); ``` ##### 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 `$client->beta->deploymentRuns->list(?\Datetime createdAtGt, ?\Datetime createdAtGte, ?\Datetime createdAtLt, ?\Datetime createdAtLte, ?string deploymentID, ?bool hasError, ?int limit, ?string page, ?BetaManagedAgentsTriggerType triggerType, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/deployment_runs` List Deployment Runs #### Parameters - `createdAtGt?: optional \Datetime` (query parameter) Return runs created strictly after this time (exclusive). - `createdAtGte?: optional \Datetime` (query parameter) Return runs created at or after this time (inclusive). - `createdAtLt?: optional \Datetime` (query parameter) Return runs created strictly before this time (exclusive). - `createdAtLte?: optional \Datetime` (query parameter) Return runs created at or before this time (inclusive). - `deploymentID?: 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. - `hasError?: optional bool` (query parameter) Filter: true for runs with non-null `error`, false for runs with non-null `session_id`. Omit for all. - `limit?: optional int` (query parameter) Maximum results per page. Default 20, maximum 1000. - `page?: optional string` (query parameter) Opaque pagination cursor. Pass `next_page` from the previous response. Invalid or expired cursors return 400. - `triggerType?: optional BetaManagedAgentsTriggerType` (query parameter) Filter runs by what triggered them. Omit to return all runs. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsDeploymentRun` - `"deployment_run" type` - `string id` Unique identifier for this run (`drun_...`). - `BetaManagedAgentsAgentReference agent` Snapshot of the agent at fire time. Always fully resolved — deployments pin agent + version. - `\Datetime createdAt` Time this run record was persisted. - `string deploymentID` ID of the deployment that produced this run. - `?Error error` Populated on creation failure. Null on success. Exactly one of `session_id` or `error` is non-null. - `?string sessionID` Populated on success. Null on creation failure. Exactly one of `session_id` or `error` is non-null. - `BetaManagedAgentsTriggerContext triggerContext` What triggered this run and trigger-specific metadata. #### Example ```php beta->deploymentRuns->list( createdAtGt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtGte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtLt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtLte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), deploymentID: 'deployment_id', hasError: true, limit: 0, page: 'page', triggerType: BetaManagedAgentsTriggerType::SCHEDULE, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->deploymentRuns->retrieve(string deploymentRunID, ?list betas, ?string workspaceID): BetaManagedAgentsDeploymentRun` **GET** `/v1/deployment_runs/{deployment_run_id}` Get Deployment Run #### Parameters - `deploymentRunID: string` (path parameter) Unique identifier of the deployment run. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsDeploymentRun` - `"deployment_run" type` - `string id` Unique identifier for this run (`drun_...`). - `BetaManagedAgentsAgentReference agent` Snapshot of the agent at fire time. Always fully resolved — deployments pin agent + version. - `\Datetime createdAt` Time this run record was persisted. - `string deploymentID` ID of the deployment that produced this run. - `?Error error` Populated on creation failure. Null on success. Exactly one of `session_id` or `error` is non-null. - `?string sessionID` Populated on success. Null on creation failure. Exactly one of `session_id` or `error` is non-null. - `BetaManagedAgentsTriggerContext triggerContext` What triggered this run and trigger-specific metadata. #### Example ```php beta->deploymentRuns->retrieve( 'deployment_run_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsDeploymentRun); ``` ##### 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 `$client->beta->vaults->create(string displayName, ?array metadata, ?list betas, ?string workspaceID): BetaManagedAgentsVault` **POST** `/v1/vaults` Create a Vault #### Parameters - `displayName: string` Human-readable name for the vault. 1-255 characters. - `metadata?: optional array` Arbitrary key-value metadata to attach to the vault. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsVault` - `"vault" type` - `string id` The unique ID of the vault (`vlt_...`). - `?\Datetime archivedAt` When the vault was archived. Null if not archived. - `\Datetime createdAt` A timestamp in RFC 3339 format - `string displayName` Human-readable name for the vault. - `array metadata` Arbitrary key-value metadata attached to the vault. - `\Datetime updatedAt` A timestamp in RFC 3339 format #### Example ```php beta->vaults->create( displayName: 'Example vault', metadata: ['environment' => 'production'], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsVault); ``` ##### 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 `$client->beta->vaults->list(?bool includeArchived, ?int limit, ?string page, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/vaults` List Vaults #### Parameters - `includeArchived?: optional bool` (query parameter) Whether to include archived vaults in the results. Defaults to `false`. - `limit?: optional int` (query parameter) Maximum number of vaults to return per page. Defaults to 20, maximum 100. - `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=php) response, to get the next page. Leave it out to get the first page. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsVault` - `"vault" type` - `string id` The unique ID of the vault (`vlt_...`). - `?\Datetime archivedAt` When the vault was archived. Null if not archived. - `\Datetime createdAt` A timestamp in RFC 3339 format - `string displayName` Human-readable name for the vault. - `array metadata` Arbitrary key-value metadata attached to the vault. - `\Datetime updatedAt` A timestamp in RFC 3339 format #### Example ```php beta->vaults->list( includeArchived: true, limit: 0, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->vaults->retrieve(string vaultID, ?list betas, ?string workspaceID): BetaManagedAgentsVault` **GET** `/v1/vaults/{vault_id}` Retrieve a Vault #### Parameters - `vaultID: string` (path parameter) Unique identifier of the vault to retrieve. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsVault` - `"vault" type` - `string id` The unique ID of the vault (`vlt_...`). - `?\Datetime archivedAt` When the vault was archived. Null if not archived. - `\Datetime createdAt` A timestamp in RFC 3339 format - `string displayName` Human-readable name for the vault. - `array metadata` Arbitrary key-value metadata attached to the vault. - `\Datetime updatedAt` A timestamp in RFC 3339 format #### Example ```php beta->vaults->retrieve( 'vlt_011CZkZDLs7fYzm1hXNPeRjv', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsVault); ``` ##### 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 `$client->beta->vaults->update(string vaultID, ?string displayName, ?array metadata, ?list betas, ?string workspaceID): BetaManagedAgentsVault` **POST** `/v1/vaults/{vault_id}` Update a Vault #### Parameters - `vaultID: string` (path parameter) Unique identifier of the vault to update. - `displayName?: optional string` Updated human-readable name for the vault. 1-255 characters. - `metadata?: optional array` Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsVault` - `"vault" type` - `string id` The unique ID of the vault (`vlt_...`). - `?\Datetime archivedAt` When the vault was archived. Null if not archived. - `\Datetime createdAt` A timestamp in RFC 3339 format - `string displayName` Human-readable name for the vault. - `array metadata` Arbitrary key-value metadata attached to the vault. - `\Datetime updatedAt` A timestamp in RFC 3339 format #### Example ```php beta->vaults->update( 'vlt_011CZkZDLs7fYzm1hXNPeRjv', displayName: 'Example vault', metadata: ['environment' => 'production'], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsVault); ``` ##### 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 `$client->beta->vaults->delete(string vaultID, ?list betas, ?string workspaceID): BetaManagedAgentsDeletedVault` **DELETE** `/v1/vaults/{vault_id}` Delete a Vault #### Parameters - `vaultID: string` (path parameter) Unique identifier of the vault to delete. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsDeletedVault` - `"vault_deleted" type` - `string id` The unique ID of the deleted vault (`vlt_...`). #### Example ```php beta->vaults->delete( 'vlt_011CZkZDLs7fYzm1hXNPeRjv', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsDeletedVault); ``` ##### Response (200) ```json { "id": "vlt_011CZkZDLs7fYzm1hXNPeRjv", "type": "vault_deleted" } ``` ### Archive a Vault `$client->beta->vaults->archive(string vaultID, ?list betas, ?string workspaceID): BetaManagedAgentsVault` **POST** `/v1/vaults/{vault_id}/archive` Archive a Vault #### Parameters - `vaultID: string` (path parameter) Unique identifier of the vault to archive. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsVault` - `"vault" type` - `string id` The unique ID of the vault (`vlt_...`). - `?\Datetime archivedAt` When the vault was archived. Null if not archived. - `\Datetime createdAt` A timestamp in RFC 3339 format - `string displayName` Human-readable name for the vault. - `array metadata` Arbitrary key-value metadata attached to the vault. - `\Datetime updatedAt` A timestamp in RFC 3339 format #### Example ```php beta->vaults->archive( 'vlt_011CZkZDLs7fYzm1hXNPeRjv', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsVault); ``` ##### 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 `$client->beta->vaults->credentials->create(string vaultID, Auth auth, ?string displayName, ?array metadata, ?list betas, ?string workspaceID): ManagedAgentsCredential` **POST** `/v1/vaults/{vault_id}/credentials` Create a Credential #### Parameters - `vaultID: string` (path parameter) Identifier of the vault to create the credential in. - `auth: Auth` Authentication configuration for the credential. - `displayName?: optional string` Human-readable name for the credential. Up to 255 characters. - `metadata?: optional array` Arbitrary key-value metadata to attach to the credential. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsCredential` - `"vault_credential" type` - `string id` The unique ID of the credential (`vcrd_...`). - `?\Datetime archivedAt` When the credential was archived. Null if not archived. - `Auth auth` Authentication configuration for this credential. - `\Datetime createdAt` A timestamp in RFC 3339 format - `array metadata` Arbitrary key-value metadata attached to the credential. - `\Datetime updatedAt` A timestamp in RFC 3339 format - `string vaultID` Identifier of the vault this credential belongs to. - `?string displayName` Human-readable name for the credential. #### Example ```php beta->vaults->credentials->create( 'vlt_011CZkZDLs7fYzm1hXNPeRjv', auth: [ 'token' => 'bearer_exampletoken', 'mcpServerURL' => 'https://example-server.modelcontextprotocol.io/sse', 'type' => 'static_bearer', ], displayName: 'Example credential', metadata: ['environment' => 'production'], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsCredential); ``` ##### 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 `$client->beta->vaults->credentials->list(string vaultID, ?bool includeArchived, ?int limit, ?string page, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/vaults/{vault_id}/credentials` List Credentials #### Parameters - `vaultID: string` (path parameter) Identifier of the vault to list credentials for. - `includeArchived?: optional bool` (query parameter) Whether to include archived credentials in the results. Defaults to `false`. - `limit?: optional int` (query parameter) Maximum number of credentials to return per page. Defaults to 20, maximum 100. - `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=php) response, to get the next page. Leave it out to get the first page. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsCredential` - `"vault_credential" type` - `string id` The unique ID of the credential (`vcrd_...`). - `?\Datetime archivedAt` When the credential was archived. Null if not archived. - `Auth auth` Authentication configuration for this credential. - `\Datetime createdAt` A timestamp in RFC 3339 format - `array metadata` Arbitrary key-value metadata attached to the credential. - `\Datetime updatedAt` A timestamp in RFC 3339 format - `string vaultID` Identifier of the vault this credential belongs to. - `?string displayName` Human-readable name for the credential. #### Example ```php beta->vaults->credentials->list( 'vlt_011CZkZDLs7fYzm1hXNPeRjv', includeArchived: true, limit: 0, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->vaults->credentials->retrieve(string credentialID, string vaultID, ?list betas, ?string workspaceID): ManagedAgentsCredential` **GET** `/v1/vaults/{vault_id}/credentials/{credential_id}` Retrieve a Credential #### Parameters - `vaultID: string` (path parameter) Identifier of the vault containing the credential. - `credentialID: string` (path parameter) Unique identifier of the credential to retrieve. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsCredential` - `"vault_credential" type` - `string id` The unique ID of the credential (`vcrd_...`). - `?\Datetime archivedAt` When the credential was archived. Null if not archived. - `Auth auth` Authentication configuration for this credential. - `\Datetime createdAt` A timestamp in RFC 3339 format - `array metadata` Arbitrary key-value metadata attached to the credential. - `\Datetime updatedAt` A timestamp in RFC 3339 format - `string vaultID` Identifier of the vault this credential belongs to. - `?string displayName` Human-readable name for the credential. #### Example ```php beta->vaults->credentials->retrieve( 'vcrd_011CZkZEMt8gZan2iYPQfSkw', vaultID: 'vlt_011CZkZDLs7fYzm1hXNPeRjv', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsCredential); ``` ##### 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 `$client->beta->vaults->credentials->update(string credentialID, string vaultID, ?Auth auth, ?string displayName, ?array metadata, ?list betas, ?string workspaceID): ManagedAgentsCredential` **POST** `/v1/vaults/{vault_id}/credentials/{credential_id}` Update a Credential #### Parameters - `vaultID: string` (path parameter) Identifier of the vault containing the credential. - `credentialID: string` (path parameter) Unique identifier of the credential to update. - `auth?: optional Auth` New authentication settings for the credential. The `type` must match the credential's current type, which can't be changed. - `displayName?: optional string` Updated human-readable name for the credential. 1-255 characters. - `metadata?: optional array` Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsCredential` - `"vault_credential" type` - `string id` The unique ID of the credential (`vcrd_...`). - `?\Datetime archivedAt` When the credential was archived. Null if not archived. - `Auth auth` Authentication configuration for this credential. - `\Datetime createdAt` A timestamp in RFC 3339 format - `array metadata` Arbitrary key-value metadata attached to the credential. - `\Datetime updatedAt` A timestamp in RFC 3339 format - `string vaultID` Identifier of the vault this credential belongs to. - `?string displayName` Human-readable name for the credential. #### Example ```php beta->vaults->credentials->update( 'vcrd_011CZkZEMt8gZan2iYPQfSkw', vaultID: 'vlt_011CZkZDLs7fYzm1hXNPeRjv', auth: [ 'type' => 'mcp_oauth', 'accessToken' => 'access_token', 'expiresAt' => new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), 'refresh' => [ 'refreshToken' => 'x', 'scope' => 'scope', 'tokenEndpointAuth' => [ 'type' => 'client_secret_basic', 'clientSecret' => 'x' ], ], ], displayName: 'Example credential', metadata: ['environment' => 'production'], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsCredential); ``` ##### 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 `$client->beta->vaults->credentials->delete(string credentialID, string vaultID, ?list betas, ?string workspaceID): ManagedAgentsDeletedCredential` **DELETE** `/v1/vaults/{vault_id}/credentials/{credential_id}` Delete a Credential #### Parameters - `vaultID: string` (path parameter) Identifier of the vault containing the credential. - `credentialID: string` (path parameter) Unique identifier of the credential to delete. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsDeletedCredential` - `"vault_credential_deleted" type` - `string id` The unique ID of the deleted credential (`vcrd_...`). #### Example ```php beta ->vaults ->credentials ->delete( 'vcrd_011CZkZEMt8gZan2iYPQfSkw', vaultID: 'vlt_011CZkZDLs7fYzm1hXNPeRjv', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsDeletedCredential); ``` ##### Response (200) ```json { "id": "vcrd_011CZkZEMt8gZan2iYPQfSkw", "type": "vault_credential_deleted" } ``` ### Archive a Credential `$client->beta->vaults->credentials->archive(string credentialID, string vaultID, ?list betas, ?string workspaceID): ManagedAgentsCredential` **POST** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` Archive a Credential #### Parameters - `vaultID: string` (path parameter) Identifier of the vault containing the credential. - `credentialID: string` (path parameter) Unique identifier of the credential to archive. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsCredential` - `"vault_credential" type` - `string id` The unique ID of the credential (`vcrd_...`). - `?\Datetime archivedAt` When the credential was archived. Null if not archived. - `Auth auth` Authentication configuration for this credential. - `\Datetime createdAt` A timestamp in RFC 3339 format - `array metadata` Arbitrary key-value metadata attached to the credential. - `\Datetime updatedAt` A timestamp in RFC 3339 format - `string vaultID` Identifier of the vault this credential belongs to. - `?string displayName` Human-readable name for the credential. #### Example ```php beta->vaults->credentials->archive( 'vcrd_011CZkZEMt8gZan2iYPQfSkw', vaultID: 'vlt_011CZkZDLs7fYzm1hXNPeRjv', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsCredential); ``` ##### 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 `$client->beta->vaults->credentials->mcpOAuthValidate(string credentialID, string vaultID, ?list betas, ?string workspaceID): ManagedAgentsCredentialValidation` **POST** `/v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate` Validate an MCP OAuth Credential #### Parameters - `vaultID: string` (path parameter) Identifier of the vault containing the credential. - `credentialID: string` (path parameter) Unique identifier of the credential to validate. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsCredentialValidation` - `"vault_credential_validation" type` - `string credentialID` Unique identifier of the credential that was validated. - `bool hasRefreshToken` Whether the credential has a refresh token configured. - `?ManagedAgentsMCPProbe mcpProbe` Details of the MCP probe step that failed, or `null` if the probe succeeded or there was no access token to test. - `?ManagedAgentsRefreshObject refresh` Details of the refresh-token exchange attempted on a 401. Null when no refresh was attempted. - `ManagedAgentsCredentialValidationStatus status` Overall verdict of the validation probe. - `\Datetime validatedAt` When the validation probe was performed. - `string vaultID` Identifier of the vault containing the credential. #### Example ```php beta ->vaults ->credentials ->mcpOAuthValidate( 'vcrd_011CZkZEMt8gZan2iYPQfSkw', vaultID: 'vlt_011CZkZDLs7fYzm1hXNPeRjv', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsCredentialValidation); ``` ##### 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 `$client->beta->memoryStores->create(string name, ?string description, ?array metadata, ?list betas, ?string workspaceID): BetaManagedAgentsMemoryStore` **POST** `/v1/memory_stores` Create a Memory Store #### Parameters - `name: string` The name of the memory store, 1 to 255 characters long, without control characters. Names don't have to be unique in a workspace. In a session, the store's directory under `/mnt/memory/` is based on this name. The name is lowercased and every run of characters other than ASCII letters and digits becomes one hyphen. The session's memory store resource gives the exact path in `mount_path`. See the [memory guide](https://platform.claude.com/docs/en/managed-agents/memory?sdk_languages=php#how-the-agent-accesses-memory) to learn more about how agents access memory stores. - `description?: optional string` Free-text description of what the store contains, up to 1,024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent. - `metadata?: optional array` Key-value pairs for your own use, such as the end user that the store belongs to. The agent doesn't see them. A store has at most 16 pairs. Keys are 1 to 64 characters long and values at most 512 characters. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsMemoryStore` - `"memory_store" type` - `string id` The unique ID of the memory store (`memstore_...`). Use it to attach the store to a session. - `?\Datetime archivedAt` When the memory store was archived, in RFC 3339, or `null` if it hasn't been. Archiving can't be undone. An archived store can't be attached to new sessions. You can't create or update its memories or update the store. You can still read and delete its memories, redact their versions, and delete the store. See the [memory guide](https://platform.claude.com/docs/en/managed-agents/memory?sdk_languages=php#archive-a-store) to learn more about archiving. - `\Datetime createdAt` When the memory store was created, in RFC 3339. - `string description` Free-text description of what the store contains, up to 1,024 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. - `array metadata` Key-value pairs for your own use, such as the end user that the store belongs to. A store has at most 16 pairs. Keys are 1 to 64 characters long and values at most 512 characters. You can't filter lists by metadata. - `string name` Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. - `\Datetime updatedAt` When the memory store was last changed, in RFC 3339. Changing its `name`, `description`, or `metadata` updates it. Archiving the store does too. Changes to the store's memories don't. #### Example ```php beta->memoryStores->create( name: 'x', description: 'description', metadata: ['foo' => 'string'], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsMemoryStore); ``` ##### 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 `$client->beta->memoryStores->list(?\Datetime createdAtGte, ?\Datetime createdAtLte, ?bool includeArchived, ?int limit, ?string page, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/memory_stores` List Memory Stores #### Parameters - `createdAtGte?: optional \Datetime` (query parameter) Return only memory stores created at or after this time (inclusive). - `createdAtLte?: optional \Datetime` (query parameter) Return only memory stores created at or before this time (inclusive). - `includeArchived?: optional bool` (query parameter) When `true`, archived stores are included in the results. Defaults to `false` (archived stores are excluded). - `limit?: optional int` (query parameter) Maximum number of stores to return per page. Must be between 1 and 100. Defaults to 20 when omitted. - `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. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsMemoryStore` - `"memory_store" type` - `string id` The unique ID of the memory store (`memstore_...`). Use it to attach the store to a session. - `?\Datetime archivedAt` When the memory store was archived, in RFC 3339, or `null` if it hasn't been. Archiving can't be undone. An archived store can't be attached to new sessions. You can't create or update its memories or update the store. You can still read and delete its memories, redact their versions, and delete the store. See the [memory guide](https://platform.claude.com/docs/en/managed-agents/memory?sdk_languages=php#archive-a-store) to learn more about archiving. - `\Datetime createdAt` When the memory store was created, in RFC 3339. - `string description` Free-text description of what the store contains, up to 1,024 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. - `array metadata` Key-value pairs for your own use, such as the end user that the store belongs to. A store has at most 16 pairs. Keys are 1 to 64 characters long and values at most 512 characters. You can't filter lists by metadata. - `string name` Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. - `\Datetime updatedAt` When the memory store was last changed, in RFC 3339. Changing its `name`, `description`, or `metadata` updates it. Archiving the store does too. Changes to the store's memories don't. #### Example ```php beta->memoryStores->list( createdAtGte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtLte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), includeArchived: true, limit: 0, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->memoryStores->retrieve(string memoryStoreID, ?list betas, ?string workspaceID): BetaManagedAgentsMemoryStore` **GET** `/v1/memory_stores/{memory_store_id}` Retrieve a Memory Store #### Parameters - `memoryStoreID: string` (path parameter) The ID of the memory store to retrieve (`memstore_...`). - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsMemoryStore` - `"memory_store" type` - `string id` The unique ID of the memory store (`memstore_...`). Use it to attach the store to a session. - `?\Datetime archivedAt` When the memory store was archived, in RFC 3339, or `null` if it hasn't been. Archiving can't be undone. An archived store can't be attached to new sessions. You can't create or update its memories or update the store. You can still read and delete its memories, redact their versions, and delete the store. See the [memory guide](https://platform.claude.com/docs/en/managed-agents/memory?sdk_languages=php#archive-a-store) to learn more about archiving. - `\Datetime createdAt` When the memory store was created, in RFC 3339. - `string description` Free-text description of what the store contains, up to 1,024 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. - `array metadata` Key-value pairs for your own use, such as the end user that the store belongs to. A store has at most 16 pairs. Keys are 1 to 64 characters long and values at most 512 characters. You can't filter lists by metadata. - `string name` Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. - `\Datetime updatedAt` When the memory store was last changed, in RFC 3339. Changing its `name`, `description`, or `metadata` updates it. Archiving the store does too. Changes to the store's memories don't. #### Example ```php beta->memoryStores->retrieve( 'memory_store_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsMemoryStore); ``` ##### 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 `$client->beta->memoryStores->update(string memoryStoreID, ?string description, ?array metadata, ?string name, ?list betas, ?string workspaceID): BetaManagedAgentsMemoryStore` **POST** `/v1/memory_stores/{memory_store_id}` Update a Memory Store #### Parameters - `memoryStoreID: string` (path parameter) The ID of the memory store to update (`memstore_...`). The request fails with HTTP status 400 if the store is archived. - `description?: optional string` New description for the store, up to 1,024 characters. Pass an empty string to clear it. - `metadata?: optional array` Changes to apply to the memory store's metadata. Keys you leave out keep their values. Set a key to a string to add or replace it, or to `null` to remove it. After the change, the metadata can hold at most 16 key-value pairs. Keys are 1 to 64 characters long and values at most 512 characters. - `name?: optional string` The new name of the memory store, 1 to 255 characters long, without control characters. Sessions created after the change use the new name for the store's directory under `/mnt/memory/`. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsMemoryStore` - `"memory_store" type` - `string id` The unique ID of the memory store (`memstore_...`). Use it to attach the store to a session. - `?\Datetime archivedAt` When the memory store was archived, in RFC 3339, or `null` if it hasn't been. Archiving can't be undone. An archived store can't be attached to new sessions. You can't create or update its memories or update the store. You can still read and delete its memories, redact their versions, and delete the store. See the [memory guide](https://platform.claude.com/docs/en/managed-agents/memory?sdk_languages=php#archive-a-store) to learn more about archiving. - `\Datetime createdAt` When the memory store was created, in RFC 3339. - `string description` Free-text description of what the store contains, up to 1,024 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. - `array metadata` Key-value pairs for your own use, such as the end user that the store belongs to. A store has at most 16 pairs. Keys are 1 to 64 characters long and values at most 512 characters. You can't filter lists by metadata. - `string name` Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. - `\Datetime updatedAt` When the memory store was last changed, in RFC 3339. Changing its `name`, `description`, or `metadata` updates it. Archiving the store does too. Changes to the store's memories don't. #### Example ```php beta->memoryStores->update( 'memory_store_id', description: 'description', metadata: ['foo' => 'string'], name: 'x', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsMemoryStore); ``` ##### 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 `$client->beta->memoryStores->delete(string memoryStoreID, ?list betas, ?string workspaceID): BetaManagedAgentsDeletedMemoryStore` **DELETE** `/v1/memory_stores/{memory_store_id}` Delete a Memory Store #### Parameters - `memoryStoreID: string` (path parameter) The ID of the memory store to delete (`memstore_...`). Deleting a store also deletes all its memories and memory versions. It can't be undone. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsDeletedMemoryStore` - `"memory_store_deleted" type` - `string id` ID of the deleted memory store (a `memstore_...` identifier). The store and all its memories and versions are no longer retrievable. #### Example ```php beta->memoryStores->delete( 'memory_store_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsDeletedMemoryStore); ``` ##### Response (200) ```json { "id": "id", "type": "memory_store_deleted" } ``` ### Archive a Memory Store `$client->beta->memoryStores->archive(string memoryStoreID, ?list betas, ?string workspaceID): BetaManagedAgentsMemoryStore` **POST** `/v1/memory_stores/{memory_store_id}/archive` Archive a Memory Store #### Parameters - `memoryStoreID: string` (path parameter) The ID of the memory store to archive (`memstore_...`). Archiving can't be undone. Archiving a store that is already archived returns it unchanged. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class BetaManagedAgentsMemoryStore` - `"memory_store" type` - `string id` The unique ID of the memory store (`memstore_...`). Use it to attach the store to a session. - `?\Datetime archivedAt` When the memory store was archived, in RFC 3339, or `null` if it hasn't been. Archiving can't be undone. An archived store can't be attached to new sessions. You can't create or update its memories or update the store. You can still read and delete its memories, redact their versions, and delete the store. See the [memory guide](https://platform.claude.com/docs/en/managed-agents/memory?sdk_languages=php#archive-a-store) to learn more about archiving. - `\Datetime createdAt` When the memory store was created, in RFC 3339. - `string description` Free-text description of what the store contains, up to 1,024 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. - `array metadata` Key-value pairs for your own use, such as the end user that the store belongs to. A store has at most 16 pairs. Keys are 1 to 64 characters long and values at most 512 characters. You can't filter lists by metadata. - `string name` Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. - `\Datetime updatedAt` When the memory store was last changed, in RFC 3339. Changing its `name`, `description`, or `metadata` updates it. Archiving the store does too. Changes to the store's memories don't. #### Example ```php beta->memoryStores->archive( 'memory_store_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsMemoryStore); ``` ##### 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 `$client->beta->memoryStores->memories->create(string memoryStoreID, ?string content, string path, ?ManagedAgentsMemoryView view, ?list betas, ?string workspaceID): ManagedAgentsMemory` **POST** `/v1/memory_stores/{memory_store_id}/memories` Create a Memory #### Parameters - `memoryStoreID: string` (path parameter) The ID of the memory store to create the memory in (`memstore_...`). - `content: string` The UTF-8 text content of the new memory. Pass `""` to create an empty memory. The maximum size is 100 kB (102,400 bytes). - `path: string` The path of the new memory, such as `/projects/foo/notes.md`. Paths are case-sensitive. A path starts with `/` and has 1 to 20 segments. A segment can't be empty and can't be `.` or `..`. A path can't contain control characters, format characters, or the line and paragraph separators U+2028 and U+2029. It must be in Unicode Normalization Form C and at most 1,024 bytes long. - `view?: optional ManagedAgentsMemoryView` (query parameter) Whether a `memory` or `memory_version` in the response includes its `content`. Defaults to `full` on retrieve operations and to `basic` on list, create, and update operations. With `full`, list operations return at most 20 items per page. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsMemory` - `"memory" type` - `string id` The unique ID of the memory (`mem_...`). It stays the same when the memory's path changes. To retrieve, update, or delete the memory, pass this ID. - `string contentSha256` Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`. - `int contentSizeBytes` The size of the memory's `content` in UTF-8 bytes. It is set regardless of `view`. - `\Datetime createdAt` When this memory was created, in RFC 3339 format. - `string memoryStoreID` ID of the memory store this memory belongs to (a `memstore_...` value). - `string memoryVersionID` The ID of the memory version that holds the memory's current content (`memver_...`). Memory versions don't have a flag that marks the latest one. Compare their IDs with this field instead. See the [memory guide](https://platform.claude.com/docs/en/managed-agents/memory?sdk_languages=php#audit-memory-changes) to learn more about memory versions. - `string path` Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes. - `\Datetime updatedAt` When the memory was last changed, in RFC 3339. To find out who made the change, look at `created_by` on the memory version that `memory_version_id` references. - `?string content` The memory's UTF-8 text content, or `null` when the response uses `view=basic`. The maximum size is 100 kB (102,400 bytes). #### Example ```php beta->memoryStores->memories->create( 'memory_store_id', content: 'content', path: '/P', view: ManagedAgentsMemoryView::BASIC, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsMemory); ``` ##### 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 `$client->beta->memoryStores->memories->list(string memoryStoreID, ?int depth, ?int limit, ?string page, ?string pathPrefix, ?ManagedAgentsMemoryView view, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/memory_stores/{memory_store_id}/memories` List Memories #### Parameters - `memoryStoreID: string` (path parameter) The ID of the memory store to list memories from (`memstore_...`). - `depth?: optional int` (query parameter) How far below `path_prefix` to list. Defaults to `0`, which lists every memory below the prefix. Pass `1` to list only the direct children. Deeper memories are then grouped into `memory_prefix` items. - `limit?: optional int` (query parameter) The maximum number of items to return per page, from 1 to 100. Defaults to 20. With `view=full`, a page holds at most 20 items. `memory` and `memory_prefix` items both count toward the limit. - `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. - `pathPrefix?: optional string` (query parameter) Return only memories whose path starts with this prefix, such as `/notes/`. This value appears in request URLs. Do not include secrets or personally identifiable information. Omit it to list the whole store. The prefix must end with `/` and matches whole segments, so `/notes/` matches `/notes/todo.md` but not `/notes-archive/todo.md`. - `view?: optional ManagedAgentsMemoryView` (query parameter) Whether each memory in the response includes `content`. Defaults to `basic`, which sets it to `null`. With `full`, a page holds at most 20 items. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsMemoryListItem` - `class ManagedAgentsMemory` - `"memory" type` - `string id` The unique ID of the memory (`mem_...`). It stays the same when the memory's path changes. To retrieve, update, or delete the memory, pass this ID. - `string contentSha256` Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`. - `int contentSizeBytes` The size of the memory's `content` in UTF-8 bytes. It is set regardless of `view`. - `\Datetime createdAt` When this memory was created, in RFC 3339 format. - `string memoryStoreID` ID of the memory store this memory belongs to (a `memstore_...` value). - `string memoryVersionID` The ID of the memory version that holds the memory's current content (`memver_...`). Memory versions don't have a flag that marks the latest one. Compare their IDs with this field instead. See the [memory guide](https://platform.claude.com/docs/en/managed-agents/memory?sdk_languages=php#audit-memory-changes) to learn more about memory versions. - `string path` Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes. - `\Datetime updatedAt` When the memory was last changed, in RFC 3339. To find out who made the change, look at `created_by` on the memory version that `memory_version_id` references. - `?string content` The memory's UTF-8 text content, or `null` when the response uses `view=basic`. The maximum size is 100 kB (102,400 bytes). - `class ManagedAgentsMemoryPrefix` - `"memory_prefix" type` - `string path` The rolled-up path prefix, including a trailing `/` (e.g. `/projects/foo/`). Pass this value as `path_prefix` on a subsequent list call to drill into the directory. #### Example ```php beta->memoryStores->memories->list( 'memory_store_id', depth: 0, limit: 0, page: 'page', pathPrefix: 'path_prefix', view: ManagedAgentsMemoryView::BASIC, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->memoryStores->memories->retrieve(string memoryID, string memoryStoreID, ?ManagedAgentsMemoryView view, ?list betas, ?string workspaceID): ManagedAgentsMemory` **GET** `/v1/memory_stores/{memory_store_id}/memories/{memory_id}` Retrieve a Memory #### Parameters - `memoryStoreID: string` (path parameter) The ID of the memory store that holds the memory (`memstore_...`). - `memoryID: string` (path parameter) The ID of the memory to retrieve (`mem_...`). - `view?: optional ManagedAgentsMemoryView` (query parameter) Whether a `memory` or `memory_version` in the response includes its `content`. Defaults to `full` on retrieve operations and to `basic` on list, create, and update operations. With `full`, list operations return at most 20 items per page. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsMemory` - `"memory" type` - `string id` The unique ID of the memory (`mem_...`). It stays the same when the memory's path changes. To retrieve, update, or delete the memory, pass this ID. - `string contentSha256` Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`. - `int contentSizeBytes` The size of the memory's `content` in UTF-8 bytes. It is set regardless of `view`. - `\Datetime createdAt` When this memory was created, in RFC 3339 format. - `string memoryStoreID` ID of the memory store this memory belongs to (a `memstore_...` value). - `string memoryVersionID` The ID of the memory version that holds the memory's current content (`memver_...`). Memory versions don't have a flag that marks the latest one. Compare their IDs with this field instead. See the [memory guide](https://platform.claude.com/docs/en/managed-agents/memory?sdk_languages=php#audit-memory-changes) to learn more about memory versions. - `string path` Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes. - `\Datetime updatedAt` When the memory was last changed, in RFC 3339. To find out who made the change, look at `created_by` on the memory version that `memory_version_id` references. - `?string content` The memory's UTF-8 text content, or `null` when the response uses `view=basic`. The maximum size is 100 kB (102,400 bytes). #### Example ```php beta->memoryStores->memories->retrieve( 'memory_id', memoryStoreID: 'memory_store_id', view: ManagedAgentsMemoryView::BASIC, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsMemory); ``` ##### 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 `$client->beta->memoryStores->memories->update(string memoryID, string memoryStoreID, ?ManagedAgentsMemoryView view, ?string content, ?string path, ?ManagedAgentsPrecondition precondition, ?list betas, ?string workspaceID): ManagedAgentsMemory` **POST** `/v1/memory_stores/{memory_store_id}/memories/{memory_id}` Update a Memory #### Parameters - `memoryStoreID: string` (path parameter) The ID of the memory store that holds the memory (`memstore_...`). - `memoryID: string` (path parameter) The ID of the memory to update (`mem_...`). - `view?: optional ManagedAgentsMemoryView` (query parameter) Whether a `memory` or `memory_version` in the response includes its `content`. Defaults to `full` on retrieve operations and to `basic` on list, create, and update operations. With `full`, list operations return at most 20 items per page. - `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` The new path of the memory, which renames it. Omit it to keep the current path. The memory keeps its `id`. A path starts with `/` and has 1 to 20 segments. A segment can't be empty and can't be `.` or `..`. A path can't contain control characters, format characters, or the line and paragraph separators U+2028 and U+2029. It must be in Unicode Normalization Form C and at most 1,024 bytes long. Paths are case-sensitive. - `precondition?: optional ManagedAgentsPrecondition` The condition that the memory must meet for the update to apply. Omit it to update unconditionally. If the condition fails, the request fails with HTTP status 409. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsMemory` - `"memory" type` - `string id` The unique ID of the memory (`mem_...`). It stays the same when the memory's path changes. To retrieve, update, or delete the memory, pass this ID. - `string contentSha256` Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`. - `int contentSizeBytes` The size of the memory's `content` in UTF-8 bytes. It is set regardless of `view`. - `\Datetime createdAt` When this memory was created, in RFC 3339 format. - `string memoryStoreID` ID of the memory store this memory belongs to (a `memstore_...` value). - `string memoryVersionID` The ID of the memory version that holds the memory's current content (`memver_...`). Memory versions don't have a flag that marks the latest one. Compare their IDs with this field instead. See the [memory guide](https://platform.claude.com/docs/en/managed-agents/memory?sdk_languages=php#audit-memory-changes) to learn more about memory versions. - `string path` Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes. - `\Datetime updatedAt` When the memory was last changed, in RFC 3339. To find out who made the change, look at `created_by` on the memory version that `memory_version_id` references. - `?string content` The memory's UTF-8 text content, or `null` when the response uses `view=basic`. The maximum size is 100 kB (102,400 bytes). #### Example ```php beta->memoryStores->memories->update( 'memory_id', memoryStoreID: 'memory_store_id', view: ManagedAgentsMemoryView::BASIC, content: 'content', path: '/P', precondition: [ 'type' => 'content_sha256', 'contentSha256' => '210b9798eb53baa4e69d31c1071cf03d212b8ad0ca30cf321e0ea82e120aac26', ], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsMemory); ``` ##### 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 `$client->beta->memoryStores->memories->delete(string memoryID, string memoryStoreID, ?string expectedContentSha256, ?list betas, ?string workspaceID): ManagedAgentsDeletedMemory` **DELETE** `/v1/memory_stores/{memory_store_id}/memories/{memory_id}` Delete a Memory #### Parameters - `memoryStoreID: string` (path parameter) The ID of the memory store that holds the memory (`memstore_...`). - `memoryID: string` (path parameter) The ID of the memory to delete (`mem_...`). - `expectedContentSha256?: 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. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsDeletedMemory` - `"memory_deleted" type` - `string id` ID of the deleted memory (a `mem_...` value). #### Example ```php beta->memoryStores->memories->delete( 'memory_id', memoryStoreID: 'memory_store_id', expectedContentSha256: 'expected_content_sha256', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsDeletedMemory); ``` ##### Response (200) ```json { "id": "id", "type": "memory_deleted" } ``` ## Beta › Memory Stores › Memory Versions ### List Memory Versions `$client->beta->memoryStores->memoryVersions->list(string memoryStoreID, ?string apiKeyID, ?\Datetime createdAtGte, ?\Datetime createdAtLte, ?int limit, ?string memoryID, ?ManagedAgentsMemoryVersionOperation operation, ?string page, ?string serviceAccountID, ?string sessionID, ?ManagedAgentsMemoryView view, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/memory_stores/{memory_store_id}/memory_versions` List Memory Versions #### Parameters - `memoryStoreID: string` (path parameter) The ID of the memory store whose version history to list (`memstore_...`). - `apiKeyID?: optional string` (query parameter) Return only versions written with the API key that has this ID. - `createdAtGte?: optional \Datetime` (query parameter) Return versions created at or after this time (inclusive). - `createdAtLte?: optional \Datetime` (query parameter) Return versions created at or before this time (inclusive). - `limit?: optional int` (query parameter) The maximum number of versions to return per page, from 1 to 100. Defaults to 20. With `view=full`, a page holds at most 20 versions. - `memoryID?: optional string` (query parameter) Return only versions of the memory with this ID (`mem_...`). The filter still works after the memory is deleted. While that memory's versions are retained, the results include the version whose `operation` is `deleted`. - `operation?: optional ManagedAgentsMemoryVersionOperation` (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. - `serviceAccountID?: optional string` (query parameter) Return only versions written by the service account with this ID (`svac_...`). - `sessionID?: optional string` (query parameter) Return only versions written by the session with this ID. - `view?: optional ManagedAgentsMemoryView` (query parameter) Whether a `memory` or `memory_version` in the response includes its `content`. Defaults to `full` on retrieve operations and to `basic` on list, create, and update operations. With `full`, list operations return at most 20 items per page. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsMemoryVersion` - `"memory_version" type` - `string id` Unique identifier for this version (a `memver_...` value). - `\Datetime createdAt` When this version was written, in RFC 3339 format. - `string memoryID` The ID of the memory that this version belongs to (`mem_...`). The ID stays 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=php) to get the memory's retained versions, including its `deleted` version while the lineage is retained. - `string memoryStoreID` ID of the memory store this version belongs to (a `memstore_...` value). - `ManagedAgentsMemoryVersionOperation operation` The kind of mutation this version records: `created`, `modified`, or `deleted`. - `?string content` The memory's UTF-8 text content as of this version. `null` when `view=basic`, when `operation` is `deleted`, or when `redacted_at` is set. - `?string contentSha256` Lowercase hex SHA-256 digest of `content` as of this version (64 characters). `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. - `?int contentSizeBytes` Size of `content` in bytes as of this version. `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. - `?ManagedAgentsActor createdBy` Who made this change to the memory, or `null` if the author wasn't recorded. Redacting the version doesn't change this field. A `session_actor` here is an agent that wrote through the store's mounted filesystem at `/mnt/memory/`. The version doesn't record the API key that created that session. So the author in `created_by` is who made the change, not who is ultimately responsible for it. You can [retrieve the session](https://platform.claude.com/docs/en/api/beta/sessions/retrieve?sdk_languages=php) to learn more about where the change came from. - `?string path` The memory's path at the time of this write. `null` if and only if `redacted_at` is set. - `?\Datetime redactedAt` When the version was redacted, in RFC 3339, or `null` if it hasn't been. When set, `content`, `path`, `content_size_bytes`, and `content_sha256` are `null`. See the [memory guide](https://platform.claude.com/docs/en/managed-agents/memory?sdk_languages=php#redact-a-version) to learn more about redaction. - `?ManagedAgentsActor redactedBy` 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). #### Example ```php beta->memoryStores->memoryVersions->list( 'memory_store_id', apiKeyID: 'api_key_id', createdAtGte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtLte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), limit: 0, memoryID: 'memory_id', operation: ManagedAgentsMemoryVersionOperation::CREATED, page: 'page', serviceAccountID: 'service_account_id', sessionID: 'session_id', view: ManagedAgentsMemoryView::BASIC, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->memoryStores->memoryVersions->retrieve(string memoryVersionID, string memoryStoreID, ?ManagedAgentsMemoryView view, ?list betas, ?string workspaceID): ManagedAgentsMemoryVersion` **GET** `/v1/memory_stores/{memory_store_id}/memory_versions/{memory_version_id}` Retrieve a Memory Version #### Parameters - `memoryStoreID: string` (path parameter) The ID of the memory store that holds the version (`memstore_...`). - `memoryVersionID: string` (path parameter) The ID of the memory version to retrieve (`memver_...`). - `view?: optional ManagedAgentsMemoryView` (query parameter) Whether a `memory` or `memory_version` in the response includes its `content`. Defaults to `full` on retrieve operations and to `basic` on list, create, and update operations. With `full`, list operations return at most 20 items per page. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsMemoryVersion` - `"memory_version" type` - `string id` Unique identifier for this version (a `memver_...` value). - `\Datetime createdAt` When this version was written, in RFC 3339 format. - `string memoryID` The ID of the memory that this version belongs to (`mem_...`). The ID stays 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=php) to get the memory's retained versions, including its `deleted` version while the lineage is retained. - `string memoryStoreID` ID of the memory store this version belongs to (a `memstore_...` value). - `ManagedAgentsMemoryVersionOperation operation` The kind of mutation this version records: `created`, `modified`, or `deleted`. - `?string content` The memory's UTF-8 text content as of this version. `null` when `view=basic`, when `operation` is `deleted`, or when `redacted_at` is set. - `?string contentSha256` Lowercase hex SHA-256 digest of `content` as of this version (64 characters). `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. - `?int contentSizeBytes` Size of `content` in bytes as of this version. `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. - `?ManagedAgentsActor createdBy` Who made this change to the memory, or `null` if the author wasn't recorded. Redacting the version doesn't change this field. A `session_actor` here is an agent that wrote through the store's mounted filesystem at `/mnt/memory/`. The version doesn't record the API key that created that session. So the author in `created_by` is who made the change, not who is ultimately responsible for it. You can [retrieve the session](https://platform.claude.com/docs/en/api/beta/sessions/retrieve?sdk_languages=php) to learn more about where the change came from. - `?string path` The memory's path at the time of this write. `null` if and only if `redacted_at` is set. - `?\Datetime redactedAt` When the version was redacted, in RFC 3339, or `null` if it hasn't been. When set, `content`, `path`, `content_size_bytes`, and `content_sha256` are `null`. See the [memory guide](https://platform.claude.com/docs/en/managed-agents/memory?sdk_languages=php#redact-a-version) to learn more about redaction. - `?ManagedAgentsActor redactedBy` 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). #### Example ```php beta ->memoryStores ->memoryVersions ->retrieve( 'memory_version_id', memoryStoreID: 'memory_store_id', view: ManagedAgentsMemoryView::BASIC, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsMemoryVersion); ``` ##### 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 `$client->beta->memoryStores->memoryVersions->redact(string memoryVersionID, string memoryStoreID, ?list betas, ?string workspaceID): ManagedAgentsMemoryVersion` **POST** `/v1/memory_stores/{memory_store_id}/memory_versions/{memory_version_id}/redact` Redact a Memory Version #### Parameters - `memoryStoreID: string` (path parameter) The ID of the memory store that holds the version (`memstore_...`). - `memoryVersionID: string` (path parameter) The ID of the memory version to redact (`memver_...`). - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `workspaceID?: 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 - `class ManagedAgentsMemoryVersion` - `"memory_version" type` - `string id` Unique identifier for this version (a `memver_...` value). - `\Datetime createdAt` When this version was written, in RFC 3339 format. - `string memoryID` The ID of the memory that this version belongs to (`mem_...`). The ID stays 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=php) to get the memory's retained versions, including its `deleted` version while the lineage is retained. - `string memoryStoreID` ID of the memory store this version belongs to (a `memstore_...` value). - `ManagedAgentsMemoryVersionOperation operation` The kind of mutation this version records: `created`, `modified`, or `deleted`. - `?string content` The memory's UTF-8 text content as of this version. `null` when `view=basic`, when `operation` is `deleted`, or when `redacted_at` is set. - `?string contentSha256` Lowercase hex SHA-256 digest of `content` as of this version (64 characters). `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. - `?int contentSizeBytes` Size of `content` in bytes as of this version. `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. - `?ManagedAgentsActor createdBy` Who made this change to the memory, or `null` if the author wasn't recorded. Redacting the version doesn't change this field. A `session_actor` here is an agent that wrote through the store's mounted filesystem at `/mnt/memory/`. The version doesn't record the API key that created that session. So the author in `created_by` is who made the change, not who is ultimately responsible for it. You can [retrieve the session](https://platform.claude.com/docs/en/api/beta/sessions/retrieve?sdk_languages=php) to learn more about where the change came from. - `?string path` The memory's path at the time of this write. `null` if and only if `redacted_at` is set. - `?\Datetime redactedAt` When the version was redacted, in RFC 3339, or `null` if it hasn't been. When set, `content`, `path`, `content_size_bytes`, and `content_sha256` are `null`. See the [memory guide](https://platform.claude.com/docs/en/managed-agents/memory?sdk_languages=php#redact-a-version) to learn more about redaction. - `?ManagedAgentsActor redactedBy` 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). #### Example ```php beta ->memoryStores ->memoryVersions ->redact( 'memory_version_id', memoryStoreID: 'memory_store_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsMemoryVersion); ``` ##### 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 `$client->beta->files->upload(FileParam | string file, ?int expiresInSeconds, ?list betas, ?string workspaceID): BetaFileMetadata` **POST** `/v1/files` Upload File #### Parameters - `file: FileParam | 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. - `expiresInSeconds?: optional int` Seconds from upload until the file expires and its bytes become permanently unavailable. Must be between 3600 (one hour) and 7776000 (ninety days). - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaFileMetadata` - `"file" type` Object type. For files, this is always `"file"`. - `string id` Unique object identifier. The format and length of IDs may change over time. - `\Datetime createdAt` RFC 3339 datetime string representing when the file was created. - `string filename` Original filename of the uploaded file. - `string mimeType` MIME type of the file. - `int sizeBytes` Size of the file in bytes. - `?bool downloadable` Whether the file can be downloaded. - `?\Datetime expiresAt` 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. - `?BetaFileScope scope` The scope of this file, indicating the context in which it was created (e.g., a session). #### Example ```php beta->files->upload( file: FileParam::fromString('Example data', filename: uniqid('file-upload-', true)), expiresInSeconds: 3600, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaFileMetadata); ``` ##### 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 `$client->beta->files->list(?list ids, ?int limit, ?string page, ?string scopeID, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/files` List Files #### Parameters - `ids?: optional list` (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 int` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. default: 20 - `page?: optional string` (query parameter) Opaque page cursor returned in a prior list response's `next_page`. Prefixed `page_`. - `scopeID?: optional string` (query parameter) Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaFileMetadata` - `"file" type` Object type. For files, this is always `"file"`. - `string id` Unique object identifier. The format and length of IDs may change over time. - `\Datetime createdAt` RFC 3339 datetime string representing when the file was created. - `string filename` Original filename of the uploaded file. - `string mimeType` MIME type of the file. - `int sizeBytes` Size of the file in bytes. - `?bool downloadable` Whether the file can be downloaded. - `?\Datetime expiresAt` 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. - `?BetaFileScope scope` The scope of this file, indicating the context in which it was created (e.g., a session). #### Example ```php beta->files->list( ids: ['string'], limit: 1, page: 'page', scopeID: 'scope_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->files->download(string fileID, ?list betas, ?string workspaceID): download` **GET** `/v1/files/{file_id}/content` Download File #### Parameters - `fileID: string` (path parameter) ID of the File. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `mixed` #### Example ```php beta->files->download( 'file_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($response); ``` ### Get File Metadata `$client->beta->files->retrieveMetadata(string fileID, ?list betas, ?string workspaceID): BetaFileMetadata` **GET** `/v1/files/{file_id}` Get File Metadata #### Parameters - `fileID: string` (path parameter) ID of the File. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaFileMetadata` - `"file" type` Object type. For files, this is always `"file"`. - `string id` Unique object identifier. The format and length of IDs may change over time. - `\Datetime createdAt` RFC 3339 datetime string representing when the file was created. - `string filename` Original filename of the uploaded file. - `string mimeType` MIME type of the file. - `int sizeBytes` Size of the file in bytes. - `?bool downloadable` Whether the file can be downloaded. - `?\Datetime expiresAt` 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. - `?BetaFileScope scope` The scope of this file, indicating the context in which it was created (e.g., a session). #### Example ```php beta->files->retrieveMetadata( 'file_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaFileMetadata); ``` ##### 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 `$client->beta->files->delete(string fileID, ?list betas, ?string workspaceID): BetaDeletedFile` **DELETE** `/v1/files/{file_id}` Delete File #### Parameters - `fileID: string` (path parameter) ID of the File. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaDeletedFile` - `?Type type` Deleted object type. For file deletion, this is always `"file_deleted"`. - `string id` ID of the deleted file. #### Example ```php beta->files->delete( 'file_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaDeletedFile); ``` ##### Response (200) ```json { "id": "file_011CNha8iCJcU1wXNR6q4V8w", "type": "file_deleted" } ``` ## Beta › Skills ### Create Skill `$client->beta->skills->create(list files, ?string displayName, ?list betas, ?string workspaceID): BetaSkill` **POST** `/v1/skills` Create Skill #### Parameters - `files: list` 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. - `displayName?: 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. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaSkill` - `"skill" type` Object type. For Skills, this is always `"skill"`. - `string id` Unique identifier for the skill. The format and length of IDs may change over time. - `\Datetime createdAt` ISO 8601 timestamp of when the skill was created. - `string displayName` 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. - `string latestVersionID` ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version. - `BetaSkillSource source` 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 - `\Datetime updatedAt` ISO 8601 timestamp of when the skill was last updated. #### Example ```php beta->skills->create( files: [ FileParam::fromString('Example data', filename: uniqid('file-upload-', true)), ], displayName: 'display_name', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaSkill); ``` ##### 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 `$client->beta->skills->list(?int limit, ?string page, ?string source, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/skills` List Skills #### Parameters - `limit?: optional int` (query parameter) Number of results to return per page. Ranges from `1` to `1000`. Defaults to `20`. default: 20 - `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 - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaSkill` - `"skill" type` Object type. For Skills, this is always `"skill"`. - `string id` Unique identifier for the skill. The format and length of IDs may change over time. - `\Datetime createdAt` ISO 8601 timestamp of when the skill was created. - `string displayName` 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. - `string latestVersionID` ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version. - `BetaSkillSource source` 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 - `\Datetime updatedAt` ISO 8601 timestamp of when the skill was last updated. #### Example ```php beta->skills->list( limit: 1, page: 'page', source: 'source', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->skills->retrieve(string skillID, ?list betas, ?string workspaceID): BetaSkill` **GET** `/v1/skills/{skill_id}` Get Skill #### Parameters - `skillID: string` (path parameter) Unique identifier for the skill. The format and length of IDs may change over time. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaSkill` - `"skill" type` Object type. For Skills, this is always `"skill"`. - `string id` Unique identifier for the skill. The format and length of IDs may change over time. - `\Datetime createdAt` ISO 8601 timestamp of when the skill was created. - `string displayName` 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. - `string latestVersionID` ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version. - `BetaSkillSource source` 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 - `\Datetime updatedAt` ISO 8601 timestamp of when the skill was last updated. #### Example ```php beta->skills->retrieve( 'skill_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaSkill); ``` ##### 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 `$client->beta->skills->delete(string skillID, ?list betas, ?string workspaceID): BetaDeletedSkill` **DELETE** `/v1/skills/{skill_id}` Delete Skill #### Parameters - `skillID: string` (path parameter) Unique identifier for the skill. The format and length of IDs may change over time. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaDeletedSkill` - `"skill_deleted" type` Deleted object type. For Skills, this is always `"skill_deleted"`. - `string id` Unique identifier for the skill. The format and length of IDs may change over time. #### Example ```php beta->skills->delete( 'skill_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaDeletedSkill); ``` ##### Response (200) ```json { "id": "skill_01JAbcdefghijklmnopqrstuvw", "type": "skill_deleted" } ``` ## Beta › Skills › Versions ### Create Skill Version `$client->beta->skills->versions->create(string skillID, list files, ?list betas, ?string workspaceID): SkillVersion` **POST** `/v1/skills/{skill_id}/versions` Create Skill Version #### Parameters - `skillID: string` (path parameter) Unique identifier for the skill. The format and length of IDs may change over time. - `files: list` 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. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class SkillVersion` - `"skill_version" type` Object type. For Skill Versions, this is always `"skill_version"`. - `string id` Unique identifier for this Skill Version. The id addresses the version in paths and pins it in references. - `\Datetime createdAt` ISO 8601 timestamp of when the skill was created. - `string description` Description of the skill version. This is extracted from the SKILL.md file in the skill upload. - `string name` 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. - `string skillID` Unique identifier for the skill. The format and length of IDs may change over time. #### Example ```php beta->skills->versions->create( 'skill_id', files: [ FileParam::fromString('Example data', filename: uniqid('file-upload-', true)), ], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaSkillVersion); ``` ##### 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 `$client->beta->skills->versions->list(string skillID, ?int limit, ?string page, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/skills/{skill_id}/versions` List Skill Versions #### Parameters - `skillID: string` (path parameter) Unique identifier for the skill. The format and length of IDs may change over time. - `limit?: optional int` (query parameter) Number of results to return per page. Ranges from `1` to `1000`. Defaults to `20`. default: 20 - `page?: optional string` (query parameter) Optionally set to the `next_page` token from the previous response. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class SkillVersion` - `"skill_version" type` Object type. For Skill Versions, this is always `"skill_version"`. - `string id` Unique identifier for this Skill Version. The id addresses the version in paths and pins it in references. - `\Datetime createdAt` ISO 8601 timestamp of when the skill was created. - `string description` Description of the skill version. This is extracted from the SKILL.md file in the skill upload. - `string name` 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. - `string skillID` Unique identifier for the skill. The format and length of IDs may change over time. #### Example ```php beta->skills->versions->list( 'skill_id', limit: 1, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->skills->versions->download(string version, string skillID, ?list betas, ?string workspaceID): download` **GET** `/v1/skills/{skill_id}/versions/{version}/content` Download a skill version's content as a zip archive. #### Parameters - `skillID: 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"). - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `mixed` #### Example ```php beta->skills->versions->download( 'version', skillID: 'skill_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($response); ``` ### Get Skill Version `$client->beta->skills->versions->retrieve(string version, string skillID, ?list betas, ?string workspaceID): SkillVersion` **GET** `/v1/skills/{skill_id}/versions/{version}` Get Skill Version #### Parameters - `skillID: 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"). - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class SkillVersion` - `"skill_version" type` Object type. For Skill Versions, this is always `"skill_version"`. - `string id` Unique identifier for this Skill Version. The id addresses the version in paths and pins it in references. - `\Datetime createdAt` ISO 8601 timestamp of when the skill was created. - `string description` Description of the skill version. This is extracted from the SKILL.md file in the skill upload. - `string name` 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. - `string skillID` Unique identifier for the skill. The format and length of IDs may change over time. #### Example ```php beta->skills->versions->retrieve( 'version', skillID: 'skill_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaSkillVersion); ``` ##### 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 `$client->beta->skills->versions->delete(string version, string skillID, ?list betas, ?string workspaceID): DeletedSkillVersion` **DELETE** `/v1/skills/{skill_id}/versions/{version}` Delete Skill Version #### Parameters - `skillID: 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"). - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class DeletedSkillVersion` - `"skill_version_deleted" type` Deleted object type. For Skill Versions, this is always `"skill_version_deleted"`. - `string id` Unique identifier for this Skill Version. The id addresses the version in paths and pins it in references. #### Example ```php beta->skills->versions->delete( 'version', skillID: 'skill_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaDeletedSkillVersion); ``` ##### Response (200) ```json { "id": "id", "type": "skill_version_deleted" } ``` ## Beta › Webhooks ### Unwrap `$client->beta->webhooks->unwrap(string body, array> headers, ?string secret): BetaWebhookEvent` Verifies the webhook signature from the `webhook-id`, `webhook-timestamp` and `webhook-signature` headers using your webhook signing key, then parses the payload into an event. Fails if the signature is missing or invalid. #### Parameters - `body: string` The body of the incoming webhook request, exactly as received: the signature is computed over these bytes. - `headers: array>` The HTTP headers of the incoming webhook request. Verification reads `webhook-id`, `webhook-timestamp` and `webhook-signature`. - `secret: optional string` The webhook signing key. Defaults to the client's `webhookKey` option. #### Returns - `class BetaWebhookEvent` - `"event" type` Object type. Always `event` for webhook payloads. - `string id` Unique event identifier for idempotency. - `\Datetime createdAt` RFC 3339 timestamp when the event occurred. - `BetaWebhookEventData data` #### Example ```php beta->webhooks->unwrap($body, $headers); var_dump($event); ``` ### Parse Unverified `$client->beta->webhooks->parseUnverified(string body): BetaWebhookEvent` Parses a webhook payload into an event without verifying its signature. Prefer `unwrap()` unless you have already verified the signature yourself. #### Parameters - `body: string` The raw JSON body of the incoming webhook request. #### Returns - `class BetaWebhookEvent` - `"event" type` Object type. Always `event` for webhook payloads. - `string id` Unique event identifier for idempotency. - `\Datetime createdAt` RFC 3339 timestamp when the event occurred. - `BetaWebhookEventData data` #### Example ```php beta->webhooks->parseUnverified($body); var_dump($event); ``` ## Beta › User Profiles ### Create User Profile `$client->beta->userProfiles->create(?AccessType accessType, ?string externalID, ?BetaUserProfileExternalUserDetailsParams externalUserDetails, ?\Datetime externalUserOnboardedAt, ?array metadata, ?string name, ?list betas, ?string workspaceID): BetaUserProfile` **POST** `/v1/user_profiles` Create User Profile #### Parameters - `accessType?: optional AccessType` 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. - `externalID?: optional string` Platform's own identifier for this user. Not enforced unique. Maximum 255 characters. Legacy field, accepted only under the `user-profiles-2026-03-24` and `user-profiles-2026-08-18` beta headers; without one of them, send `external_user_details.reference_id`. - `externalUserDetails?: optional BetaUserProfileExternalUserDetailsParams` Details about the entity this profile represents, as the platform states them. Every field is optional. Not accepted under the legacy `user-profiles-2026-03-24` and `user-profiles-2026-08-18` beta headers, which take the top-level `external_id` (and, under `user-profiles-2026-08-18`, `external_user_onboarded_at`) instead. - `externalUserOnboardedAt?: optional \Datetime` 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. Legacy field, accepted only under the `user-profiles-2026-08-18` beta header; without a legacy header, send `external_user_details.onboarded_at`. - `metadata?: optional array` 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. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaUserProfile` - `"user_profile" type` Object type. Always `user_profile`. - `string id` Unique identifier for this user profile, prefixed `uprof_`. - `\Datetime createdAt` When this user profile was created, in RFC 3339 format. - `array metadata` Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `?string name` 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. `null` until the platform supplies one. - `array trustGrants` Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight. - `\Datetime updatedAt` When this user profile was last modified, in RFC 3339 format. It normally also updates shortly after Anthropic gives the profile an approval or withdraws one. Other changes to the statuses that Anthropic reports do not always update it, so read the status itself rather than watching this timestamp. - `?AccessType accessType` How the platform uses the API for this entity: `application` (default) or `passthrough`. Absent under the legacy `user-profiles-2026-03-24` beta header. - `?string externalID` Platform's own identifier for this user. Not enforced unique. Legacy field, present only under the `user-profiles-2026-03-24` and `user-profiles-2026-08-18` beta headers; without one of them, the value is `external_user_details.reference_id`. - `?BetaUserProfileExternalUserDetails externalUserDetails` Details about the entity this profile represents, as the platform states them; not verified by Anthropic. Every field is present, `null` until the platform supplies a value. Absent under the legacy `user-profiles-2026-03-24` and `user-profiles-2026-08-18` beta headers, which serve `reference_id` as the top-level `external_id` and, under `user-profiles-2026-08-18`, `onboarded_at` as `external_user_onboarded_at`. - `?\Datetime externalUserOnboardedAt` 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. Legacy field, present only under the `user-profiles-2026-08-18` beta header; without a legacy header, the value is `external_user_details.onboarded_at`. #### Example ```php beta->userProfiles->create( accessType: 'application', externalID: 'x', externalUserDetails: [ 'accountStatus' => 'active', 'country' => 'US', 'emailHash' => 'x', 'entityType' => 'business', 'nameHash' => 'x', 'onboardedAt' => new \DateTimeImmutable('2024-11-02T08:15:00Z'), 'referenceID' => 'user_12345', ], externalUserOnboardedAt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), metadata: [], name: 'Example User', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaUserProfile); ``` ##### Response (200) ```json { "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9", "created_at": "2026-03-15T10:00:00Z", "metadata": {}, "name": "Example User", "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": "US", "email_hash": null, "entity_type": "business", "name_hash": null, "onboarded_at": "2024-11-02T08:15:00Z", "reference_id": "user_12345" }, "external_user_onboarded_at": "2024-11-02T08:15:00Z" } ``` ### List User Profiles `$client->beta->userProfiles->list(?int limit, ?Order order, ?OrderBy orderBy, ?string page, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/user_profiles` List User Profiles #### Parameters - `limit?: optional int` (query parameter) The maximum number of user profiles to return, from 1 to 100. Defaults to 20. - `order?: optional Order` (query parameter) The sort direction, applied to the field that `order_by` selects. Defaults to `desc`. - `orderBy?: optional OrderBy` (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. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaUserProfile` - `"user_profile" type` Object type. Always `user_profile`. - `string id` Unique identifier for this user profile, prefixed `uprof_`. - `\Datetime createdAt` When this user profile was created, in RFC 3339 format. - `array metadata` Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `?string name` 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. `null` until the platform supplies one. - `array trustGrants` Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight. - `\Datetime updatedAt` When this user profile was last modified, in RFC 3339 format. It normally also updates shortly after Anthropic gives the profile an approval or withdraws one. Other changes to the statuses that Anthropic reports do not always update it, so read the status itself rather than watching this timestamp. - `?AccessType accessType` How the platform uses the API for this entity: `application` (default) or `passthrough`. Absent under the legacy `user-profiles-2026-03-24` beta header. - `?string externalID` Platform's own identifier for this user. Not enforced unique. Legacy field, present only under the `user-profiles-2026-03-24` and `user-profiles-2026-08-18` beta headers; without one of them, the value is `external_user_details.reference_id`. - `?BetaUserProfileExternalUserDetails externalUserDetails` Details about the entity this profile represents, as the platform states them; not verified by Anthropic. Every field is present, `null` until the platform supplies a value. Absent under the legacy `user-profiles-2026-03-24` and `user-profiles-2026-08-18` beta headers, which serve `reference_id` as the top-level `external_id` and, under `user-profiles-2026-08-18`, `onboarded_at` as `external_user_onboarded_at`. - `?\Datetime externalUserOnboardedAt` 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. Legacy field, present only under the `user-profiles-2026-08-18` beta header; without a legacy header, the value is `external_user_details.onboarded_at`. #### Example ```php beta->userProfiles->list( limit: 0, order: 'asc', orderBy: 'created_at', page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9", "created_at": "2026-03-15T10:00:00Z", "metadata": {}, "name": "Example User", "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": "US", "email_hash": null, "entity_type": "business", "name_hash": null, "onboarded_at": "2024-11-02T08:15:00Z", "reference_id": "user_12345" }, "external_user_onboarded_at": "2024-11-02T08:15:00Z" } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ### Get User Profile `$client->beta->userProfiles->retrieve(string userProfileID, ?list betas, ?string workspaceID): BetaUserProfile` **GET** `/v1/user_profiles/{user_profile_id}` Get User Profile #### Parameters - `userProfileID: string` (path parameter) The ID of the user profile to get (`uprof_...`). - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaUserProfile` - `"user_profile" type` Object type. Always `user_profile`. - `string id` Unique identifier for this user profile, prefixed `uprof_`. - `\Datetime createdAt` When this user profile was created, in RFC 3339 format. - `array metadata` Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `?string name` 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. `null` until the platform supplies one. - `array trustGrants` Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight. - `\Datetime updatedAt` When this user profile was last modified, in RFC 3339 format. It normally also updates shortly after Anthropic gives the profile an approval or withdraws one. Other changes to the statuses that Anthropic reports do not always update it, so read the status itself rather than watching this timestamp. - `?AccessType accessType` How the platform uses the API for this entity: `application` (default) or `passthrough`. Absent under the legacy `user-profiles-2026-03-24` beta header. - `?string externalID` Platform's own identifier for this user. Not enforced unique. Legacy field, present only under the `user-profiles-2026-03-24` and `user-profiles-2026-08-18` beta headers; without one of them, the value is `external_user_details.reference_id`. - `?BetaUserProfileExternalUserDetails externalUserDetails` Details about the entity this profile represents, as the platform states them; not verified by Anthropic. Every field is present, `null` until the platform supplies a value. Absent under the legacy `user-profiles-2026-03-24` and `user-profiles-2026-08-18` beta headers, which serve `reference_id` as the top-level `external_id` and, under `user-profiles-2026-08-18`, `onboarded_at` as `external_user_onboarded_at`. - `?\Datetime externalUserOnboardedAt` 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. Legacy field, present only under the `user-profiles-2026-08-18` beta header; without a legacy header, the value is `external_user_details.onboarded_at`. #### Example ```php beta->userProfiles->retrieve( 'uprof_011CZkZCu8hGbp5mYRQgUmz9', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaUserProfile); ``` ##### Response (200) ```json { "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9", "created_at": "2026-03-15T10:00:00Z", "metadata": {}, "name": "Example User", "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": "US", "email_hash": null, "entity_type": "business", "name_hash": null, "onboarded_at": "2024-11-02T08:15:00Z", "reference_id": "user_12345" }, "external_user_onboarded_at": "2024-11-02T08:15:00Z" } ``` ### Update User Profile `$client->beta->userProfiles->update(string userProfileID, ?AccessType accessType, ?string externalID, ?BetaUserProfileExternalUserDetailsParams externalUserDetails, ?\Datetime externalUserOnboardedAt, ?array metadata, ?string name, ?list betas, ?string workspaceID): BetaUserProfile` **POST** `/v1/user_profiles/{user_profile_id}` Update User Profile #### Parameters - `userProfileID: string` (path parameter) The ID of the user profile to update (`uprof_...`). - `accessType?: optional AccessType` If present, replaces the stored access type. Omit to leave unchanged. - `externalID?: optional string` If present, replaces the stored external_id. Omit to leave unchanged. Maximum 255 characters. Legacy field, accepted only under the `user-profiles-2026-03-24` and `user-profiles-2026-08-18` beta headers; without one of them, send `external_user_details.reference_id`. - `externalUserDetails?: optional BetaUserProfileExternalUserDetailsParams` 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. Not accepted under the legacy `user-profiles-2026-03-24` and `user-profiles-2026-08-18` beta headers. - `externalUserOnboardedAt?: optional \Datetime` 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. Legacy field, accepted only under the `user-profiles-2026-08-18` beta header; without a legacy header, send `external_user_details.onboarded_at`. - `metadata?: optional array` 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. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaUserProfile` - `"user_profile" type` Object type. Always `user_profile`. - `string id` Unique identifier for this user profile, prefixed `uprof_`. - `\Datetime createdAt` When this user profile was created, in RFC 3339 format. - `array metadata` Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `?string name` 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. `null` until the platform supplies one. - `array trustGrants` Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight. - `\Datetime updatedAt` When this user profile was last modified, in RFC 3339 format. It normally also updates shortly after Anthropic gives the profile an approval or withdraws one. Other changes to the statuses that Anthropic reports do not always update it, so read the status itself rather than watching this timestamp. - `?AccessType accessType` How the platform uses the API for this entity: `application` (default) or `passthrough`. Absent under the legacy `user-profiles-2026-03-24` beta header. - `?string externalID` Platform's own identifier for this user. Not enforced unique. Legacy field, present only under the `user-profiles-2026-03-24` and `user-profiles-2026-08-18` beta headers; without one of them, the value is `external_user_details.reference_id`. - `?BetaUserProfileExternalUserDetails externalUserDetails` Details about the entity this profile represents, as the platform states them; not verified by Anthropic. Every field is present, `null` until the platform supplies a value. Absent under the legacy `user-profiles-2026-03-24` and `user-profiles-2026-08-18` beta headers, which serve `reference_id` as the top-level `external_id` and, under `user-profiles-2026-08-18`, `onboarded_at` as `external_user_onboarded_at`. - `?\Datetime externalUserOnboardedAt` 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. Legacy field, present only under the `user-profiles-2026-08-18` beta header; without a legacy header, the value is `external_user_details.onboarded_at`. #### Example ```php beta->userProfiles->update( 'uprof_011CZkZCu8hGbp5mYRQgUmz9', accessType: 'application', externalID: 'x', externalUserDetails: [ 'accountStatus' => 'suspended', 'country' => 'SE', 'emailHash' => 'x', 'entityType' => 'individual', 'nameHash' => 'x', 'onboardedAt' => new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), 'referenceID' => 'x', ], externalUserOnboardedAt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), metadata: ['foo' => 'string'], name: 'x', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaUserProfile); ``` ##### Response (200) ```json { "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9", "created_at": "2026-03-15T10:00:00Z", "metadata": {}, "name": "Example User", "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": "US", "email_hash": null, "entity_type": "business", "name_hash": null, "onboarded_at": "2024-11-02T08:15:00Z", "reference_id": "user_12345" }, "external_user_onboarded_at": "2024-11-02T08:15:00Z" } ``` ### Delete User Profile `$client->beta->userProfiles->delete(string userProfileID, ?list betas, ?string workspaceID): BetaDeletedUserProfile` **DELETE** `/v1/user_profiles/{user_profile_id}` Delete User Profile #### Parameters - `userProfileID: string` (path parameter) The ID of the user profile to delete (`uprof_...`). - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaDeletedUserProfile` - `"user_profile_deleted" type` Object type. Always `user_profile_deleted`. - `string id` Identifier of the deleted user profile, prefixed `uprof_`. #### Example ```php beta->userProfiles->delete( 'uprof_011CZkZCu8hGbp5mYRQgUmz9', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaDeletedUserProfile); ``` ##### Response (200) ```json { "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9", "type": "user_profile_deleted" } ``` ### Create Enrollment URL `$client->beta->userProfiles->createEnrollmentURL(string userProfileID, ?list betas, ?string workspaceID): BetaUserProfileEnrollmentURL` **POST** `/v1/user_profiles/{user_profile_id}/enrollment_url` Create Enrollment URL #### Parameters - `userProfileID: string` (path parameter) The ID of the user profile to create an enrollment URL for (`uprof_...`). - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class BetaUserProfileEnrollmentURL` - `"enrollment_url" type` Object type. Always `enrollment_url`. - `\Datetime expiresAt` When this enrollment URL expires, in RFC 3339 format. - `string url` Enrollment URL to send to the end user. Valid until `expires_at`. #### Example ```php beta ->userProfiles ->createEnrollmentURL( 'uprof_011CZkZCu8hGbp5mYRQgUmz9', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaUserProfileEnrollmentURL); ``` ##### Response (200) ```json { "expires_at": "2026-03-15T10:15:00Z", "type": "enrollment_url", "url": "https://platform.claude.com/user-profiles/enrollment/M3J0bGJxZ2ppMnptbnB1" } ``` ## Beta › User Profiles › Action URLs ### Create Action URL `$client->beta->userProfiles->actionURLs->create(string userProfileID, UserProfileEnrollEndUserAction action, ?list betas, ?string workspaceID): UserProfileActionURL` **POST** `/v1/user_profiles/{user_profile_id}/action_urls` Create Action URL #### Parameters - `userProfileID: string` (path parameter) The ID of the user profile the action is for (`uprof_...`). - `action: UserProfileEnrollEndUserAction` The action that the person who opens the URL takes. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. - `workspaceID?: 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 - `class UserProfileActionURL` - `"user_profile_action_url" type` Object type. Always `user_profile_action_url`. - `\Datetime expiresAt` When the URL stops working, in RFC 3339 format. - `string url` The URL to give to the person who takes the action. Anyone who holds it can open it until `expires_at`. #### Example ```php beta->userProfiles->actionURLs->create( 'uprof_011CZkZCu8hGbp5mYRQgUmz9', action: ['type' => 'enroll_end_user'], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaUserProfileActionURL); ``` ##### Response (200) ```json { "expires_at": "2026-03-15T10:15:00Z", "type": "user_profile_action_url", "url": "https://platform.claude.com/user-profiles/enrollment/M3J0bGJxZ2ppMnptbnB1" } ``` ## Beta › Dreams ### Create a Dream `$client->beta->dreams->create(list inputs, Model model, ?string instructions, ?BetaOutputBehavior outputBehavior, ?list betas, ?string workspaceID): BetaDream` **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=php#create-a-dream) to learn more about creating dreams. #### Parameters - `inputs: list` The memory store and sessions for the dream to read, as exactly one `memory_store` entry and exactly one `sessions` entry. - `model: Model` 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 [Availability section of the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=php#feature-availability) 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=php#steer-with-instructions) for what kinds of instructions work well. - `outputBehavior?: optional BetaOutputBehavior` Which memory store a dream writes its result to. Defaults to `create_new` when left out of a create request. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `dreaming-2026-04-21` in this header. - `workspaceID?: 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 - `class BetaDream` - `"dream" type` - `string id` The unique ID of the dream (`drm_...`). - `?\Datetime archivedAt` When the dream was archived, in RFC 3339, or `null` if it hasn't been archived. - `\Datetime createdAt` When the dream was created, in RFC 3339. Lists of dreams are sorted by this time, newest first. - `?\Datetime endedAt` When the dream reached `completed`, `failed`, or `canceled`, in RFC 3339, or `null` if it is still `pending` or `running`. - `?BetaDreamError error` Why the dream failed, or `null` if `status` isn't `failed`. - `list inputs` The sources that the dream reads, from the request that created it. - `?string instructions` The guidance given when the dream was created, or `null` if none was given. - `BetaDreamModelConfig model` 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. - `BetaOutputBehavior outputBehavior` 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. - `list outputs` 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=php#use-the-output) for how to review and use the result. - `?string sessionID` 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=php#watch-the-pipeline-run) for how to watch a running dream. - `BetaDreamStatus status` 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=php#lifecycle) for what each status means. - `BetaDreamUsage usage` The dream's token counts, which stop changing once its `status` is `completed` or `failed`. After a cancel, they can keep changing. #### Example ```php beta->dreams->create( inputs: [['memoryStoreID' => 'x', 'type' => 'memory_store']], model: 'string', instructions: 'x', outputBehavior: ['type' => 'create_new'], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaDream); ``` ##### 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 `$client->beta->dreams->list(?\Datetime createdAtGt, ?\Datetime createdAtLt, ?bool includeArchived, ?int limit, ?string page, ?list statuses, ?list betas, ?string workspaceID): PageCursor` **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=php#list-dreams) for how to page through dreams. #### Parameters - `createdAtGt?: optional \Datetime` (query parameter) Return only dreams created after this time (exclusive), in RFC 3339. - `createdAtLt?: optional \Datetime` (query parameter) Return only dreams created before this time (exclusive), in RFC 3339. - `includeArchived?: optional bool` (query parameter) Whether to include archived dreams. Defaults to `false`. - `limit?: optional int` (query parameter) The maximum number of dreams to return, from 1 to 100. Defaults to 20. - `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. - `statuses?: optional list` (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. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `dreaming-2026-04-21` in this header. - `workspaceID?: 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 - `class BetaDream` - `"dream" type` - `string id` The unique ID of the dream (`drm_...`). - `?\Datetime archivedAt` When the dream was archived, in RFC 3339, or `null` if it hasn't been archived. - `\Datetime createdAt` When the dream was created, in RFC 3339. Lists of dreams are sorted by this time, newest first. - `?\Datetime endedAt` When the dream reached `completed`, `failed`, or `canceled`, in RFC 3339, or `null` if it is still `pending` or `running`. - `?BetaDreamError error` Why the dream failed, or `null` if `status` isn't `failed`. - `list inputs` The sources that the dream reads, from the request that created it. - `?string instructions` The guidance given when the dream was created, or `null` if none was given. - `BetaDreamModelConfig model` 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. - `BetaOutputBehavior outputBehavior` 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. - `list outputs` 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=php#use-the-output) for how to review and use the result. - `?string sessionID` 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=php#watch-the-pipeline-run) for how to watch a running dream. - `BetaDreamStatus status` 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=php#lifecycle) for what each status means. - `BetaDreamUsage usage` The dream's token counts, which stop changing once its `status` is `completed` or `failed`. After a cancel, they can keep changing. #### Example ```php beta->dreams->list( createdAtGt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtLt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), includeArchived: true, limit: 0, page: 'page', statuses: [BetaDreamStatus::PENDING], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->dreams->retrieve(string dreamID, ?list betas, ?string workspaceID): BetaDream` **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=php#track-progress) for how to poll a dream and what each status means. #### Parameters - `dreamID: string` (path parameter) The ID of the dream to get (`drm_...`). - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `dreaming-2026-04-21` in this header. - `workspaceID?: 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 - `class BetaDream` - `"dream" type` - `string id` The unique ID of the dream (`drm_...`). - `?\Datetime archivedAt` When the dream was archived, in RFC 3339, or `null` if it hasn't been archived. - `\Datetime createdAt` When the dream was created, in RFC 3339. Lists of dreams are sorted by this time, newest first. - `?\Datetime endedAt` When the dream reached `completed`, `failed`, or `canceled`, in RFC 3339, or `null` if it is still `pending` or `running`. - `?BetaDreamError error` Why the dream failed, or `null` if `status` isn't `failed`. - `list inputs` The sources that the dream reads, from the request that created it. - `?string instructions` The guidance given when the dream was created, or `null` if none was given. - `BetaDreamModelConfig model` 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. - `BetaOutputBehavior outputBehavior` 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. - `list outputs` 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=php#use-the-output) for how to review and use the result. - `?string sessionID` 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=php#watch-the-pipeline-run) for how to watch a running dream. - `BetaDreamStatus status` 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=php#lifecycle) for what each status means. - `BetaDreamUsage usage` The dream's token counts, which stop changing once its `status` is `completed` or `failed`. After a cancel, they can keep changing. #### Example ```php beta->dreams->retrieve( 'dream_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaDream); ``` ##### 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 `$client->beta->dreams->cancel(string dreamID, ?list betas, ?string workspaceID): BetaDream` **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=php#cancel-a-dream) to learn more about canceling dreams. #### Parameters - `dreamID: string` (path parameter) The ID of the dream to cancel (`drm_...`). - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `dreaming-2026-04-21` in this header. - `workspaceID?: 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 - `class BetaDream` - `"dream" type` - `string id` The unique ID of the dream (`drm_...`). - `?\Datetime archivedAt` When the dream was archived, in RFC 3339, or `null` if it hasn't been archived. - `\Datetime createdAt` When the dream was created, in RFC 3339. Lists of dreams are sorted by this time, newest first. - `?\Datetime endedAt` When the dream reached `completed`, `failed`, or `canceled`, in RFC 3339, or `null` if it is still `pending` or `running`. - `?BetaDreamError error` Why the dream failed, or `null` if `status` isn't `failed`. - `list inputs` The sources that the dream reads, from the request that created it. - `?string instructions` The guidance given when the dream was created, or `null` if none was given. - `BetaDreamModelConfig model` 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. - `BetaOutputBehavior outputBehavior` 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. - `list outputs` 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=php#use-the-output) for how to review and use the result. - `?string sessionID` 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=php#watch-the-pipeline-run) for how to watch a running dream. - `BetaDreamStatus status` 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=php#lifecycle) for what each status means. - `BetaDreamUsage usage` The dream's token counts, which stop changing once its `status` is `completed` or `failed`. After a cancel, they can keep changing. #### Example ```php beta->dreams->cancel( 'dream_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaDream); ``` ##### 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 `$client->beta->dreams->archive(string dreamID, ?list betas, ?string workspaceID): BetaDream` **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=php#archive-a-dream) to learn more about archiving dreams. #### Parameters - `dreamID: string` (path parameter) The ID of the dream to archive (`drm_...`). - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `dreaming-2026-04-21` in this header. - `workspaceID?: 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 - `class BetaDream` - `"dream" type` - `string id` The unique ID of the dream (`drm_...`). - `?\Datetime archivedAt` When the dream was archived, in RFC 3339, or `null` if it hasn't been archived. - `\Datetime createdAt` When the dream was created, in RFC 3339. Lists of dreams are sorted by this time, newest first. - `?\Datetime endedAt` When the dream reached `completed`, `failed`, or `canceled`, in RFC 3339, or `null` if it is still `pending` or `running`. - `?BetaDreamError error` Why the dream failed, or `null` if `status` isn't `failed`. - `list inputs` The sources that the dream reads, from the request that created it. - `?string instructions` The guidance given when the dream was created, or `null` if none was given. - `BetaDreamModelConfig model` 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. - `BetaOutputBehavior outputBehavior` 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. - `list outputs` 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=php#use-the-output) for how to review and use the result. - `?string sessionID` 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=php#watch-the-pipeline-run) for how to watch a running dream. - `BetaDreamStatus status` 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=php#lifecycle) for what each status means. - `BetaDreamUsage usage` The dream's token counts, which stop changing once its `status` is `completed` or `failed`. After a cancel, they can keep changing. #### Example ```php beta->dreams->archive( 'dream_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaDream); ``` ##### 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 `$client->beta->tunnels->create(?string displayName, ?list betas, ?string workspaceID): BetaTunnel` **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 - `displayName?: optional string` Optional human-readable name for the tunnel (1-255 characters). - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `mcp-tunnels-2026-06-22` in this header. - `workspaceID?: 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 - `class BetaTunnel` - `"tunnel" type` - `string id` Unique identifier for the tunnel, prefixed with `tnl_`. - `?\Datetime archivedAt` RFC 3339 datetime string indicating when the tunnel was archived. Null if it is not archived. - `\Datetime createdAt` RFC 3339 datetime string indicating when the tunnel was created. - `?string displayName` Human-readable name for the tunnel (1-255 characters). Null if unset. - `string domain` 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 ```php beta->tunnels->create( displayName: 'x', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaTunnel); ``` ##### 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 `$client->beta->tunnels->retrieve(string tunnelID, ?list betas, ?string workspaceID): BetaTunnel` **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 - `tunnelID: string` (path parameter) ID of the tunnel (`tnl_...`). - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `mcp-tunnels-2026-06-22` in this header. - `workspaceID?: 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 - `class BetaTunnel` - `"tunnel" type` - `string id` Unique identifier for the tunnel, prefixed with `tnl_`. - `?\Datetime archivedAt` RFC 3339 datetime string indicating when the tunnel was archived. Null if it is not archived. - `\Datetime createdAt` RFC 3339 datetime string indicating when the tunnel was created. - `?string displayName` Human-readable name for the tunnel (1-255 characters). Null if unset. - `string domain` 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 ```php beta->tunnels->retrieve( 'tunnel_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaTunnel); ``` ##### 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 `$client->beta->tunnels->list(?bool includeArchived, ?int limit, ?string page, ?list betas, ?string workspaceID): PageCursor` **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 - `includeArchived?: optional bool` (query parameter) Whether to include archived tunnels in the results. Defaults to false. - `limit?: optional int` (query parameter) Maximum number of tunnels to return per page. Defaults to 20, maximum 1000. - `page?: optional string` (query parameter) Opaque pagination cursor from a previous `list_tunnels` response. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `mcp-tunnels-2026-06-22` in this header. - `workspaceID?: 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 - `class BetaTunnel` - `"tunnel" type` - `string id` Unique identifier for the tunnel, prefixed with `tnl_`. - `?\Datetime archivedAt` RFC 3339 datetime string indicating when the tunnel was archived. Null if it is not archived. - `\Datetime createdAt` RFC 3339 datetime string indicating when the tunnel was created. - `?string displayName` Human-readable name for the tunnel (1-255 characters). Null if unset. - `string domain` 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 ```php beta->tunnels->list( includeArchived: true, limit: 0, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->tunnels->archive(string tunnelID, ?list betas, ?string workspaceID): BetaTunnel` **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 - `tunnelID: string` (path parameter) ID of the tunnel (`tnl_...`). - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `mcp-tunnels-2026-06-22` in this header. - `workspaceID?: 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 - `class BetaTunnel` - `"tunnel" type` - `string id` Unique identifier for the tunnel, prefixed with `tnl_`. - `?\Datetime archivedAt` RFC 3339 datetime string indicating when the tunnel was archived. Null if it is not archived. - `\Datetime createdAt` RFC 3339 datetime string indicating when the tunnel was created. - `?string displayName` Human-readable name for the tunnel (1-255 characters). Null if unset. - `string domain` 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 ```php beta->tunnels->archive( 'tunnel_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaTunnel); ``` ##### 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 `$client->beta->tunnels->revealToken(string tunnelID, ?list betas, ?string workspaceID): BetaTunnelToken` **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 - `tunnelID: string` (path parameter) ID of the tunnel (`tnl_...`). - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `mcp-tunnels-2026-06-22` in this header. - `workspaceID?: 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 - `class BetaTunnelToken` - `"tunnel_token" type` - `string id` Stable identifier for the current token value. Changes when the token is rotated. - `string tunnelToken` The connector token used to run the tunnel. Treat as a credential. #### Example ```php beta->tunnels->revealToken( 'tunnel_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaTunnelToken); ``` ##### Response (200) ```json { "id": "id", "tunnel_token": "tunnel_token", "type": "tunnel_token" } ``` ### Rotate Tunnel Token `$client->beta->tunnels->rotateToken(string tunnelID, ?string reason, ?list betas, ?string workspaceID): BetaTunnelToken` **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 - `tunnelID: string` (path parameter) ID of the tunnel (`tnl_...`). - `reason?: optional string` Optional free-text reason for the rotation, recorded for audit. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `mcp-tunnels-2026-06-22` in this header. - `workspaceID?: 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 - `class BetaTunnelToken` - `"tunnel_token" type` - `string id` Stable identifier for the current token value. Changes when the token is rotated. - `string tunnelToken` The connector token used to run the tunnel. Treat as a credential. #### Example ```php beta->tunnels->rotateToken( 'tunnel_id', reason: 'reason', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaTunnelToken); ``` ##### Response (200) ```json { "id": "id", "tunnel_token": "tunnel_token", "type": "tunnel_token" } ``` ## Beta › Tunnels › Certificates ### Create Tunnel Certificate `$client->beta->tunnels->certificates->create(string tunnelID, string caCertificatePEM, ?list betas, ?string workspaceID): TunnelCertificate` **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 - `tunnelID: string` (path parameter) ID of the tunnel (`tnl_...`). - `caCertificatePEM: string` PEM-encoded X.509 CA certificate. Must contain exactly one certificate and no private-key material. Maximum 8KB. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `mcp-tunnels-2026-06-22` in this header. - `workspaceID?: 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 - `class TunnelCertificate` - `"tunnel_certificate" type` - `string id` Unique identifier for the certificate, prefixed with `tcrt_`. - `?\Datetime archivedAt` RFC 3339 datetime string indicating when the certificate was archived. Null if it is still in the trusted set. - `\Datetime createdAt` RFC 3339 datetime string indicating when the certificate was registered. - `?\Datetime expiresAt` RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire. - `string fingerprint` Lowercase hex SHA-256 fingerprint of the certificate's DER encoding. - `string tunnelID` ID of the tunnel the certificate is registered against. #### Example ```php beta->tunnels->certificates->create( 'tunnel_id', caCertificatePEM: 'ca_certificate_pem', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaTunnelCertificate); ``` ##### 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 `$client->beta->tunnels->certificates->retrieve(string certificateID, string tunnelID, ?list betas, ?string workspaceID): TunnelCertificate` **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 - `tunnelID: string` (path parameter) ID of the tunnel (`tnl_...`). - `certificateID: string` (path parameter) ID of the certificate (`tcrt_...`). - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `mcp-tunnels-2026-06-22` in this header. - `workspaceID?: 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 - `class TunnelCertificate` - `"tunnel_certificate" type` - `string id` Unique identifier for the certificate, prefixed with `tcrt_`. - `?\Datetime archivedAt` RFC 3339 datetime string indicating when the certificate was archived. Null if it is still in the trusted set. - `\Datetime createdAt` RFC 3339 datetime string indicating when the certificate was registered. - `?\Datetime expiresAt` RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire. - `string fingerprint` Lowercase hex SHA-256 fingerprint of the certificate's DER encoding. - `string tunnelID` ID of the tunnel the certificate is registered against. #### Example ```php beta->tunnels->certificates->retrieve( 'certificate_id', tunnelID: 'tunnel_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaTunnelCertificate); ``` ##### 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 `$client->beta->tunnels->certificates->list(string tunnelID, ?bool includeArchived, ?int limit, ?string page, ?list betas, ?string workspaceID): PageCursor` **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 - `tunnelID: string` (path parameter) ID of the tunnel (`tnl_...`). - `includeArchived?: optional bool` (query parameter) Whether to include archived certificates in the results. Defaults to false. - `limit?: optional int` (query parameter) Maximum number of certificates to return per page. Defaults to 20, maximum 1000. - `page?: optional string` (query parameter) Opaque pagination cursor from a previous `list_tunnel_certificates` response. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `mcp-tunnels-2026-06-22` in this header. - `workspaceID?: 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 - `class TunnelCertificate` - `"tunnel_certificate" type` - `string id` Unique identifier for the certificate, prefixed with `tcrt_`. - `?\Datetime archivedAt` RFC 3339 datetime string indicating when the certificate was archived. Null if it is still in the trusted set. - `\Datetime createdAt` RFC 3339 datetime string indicating when the certificate was registered. - `?\Datetime expiresAt` RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire. - `string fingerprint` Lowercase hex SHA-256 fingerprint of the certificate's DER encoding. - `string tunnelID` ID of the tunnel the certificate is registered against. #### Example ```php beta->tunnels->certificates->list( 'tunnel_id', includeArchived: true, limit: 0, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### 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 `$client->beta->tunnels->certificates->archive(string certificateID, string tunnelID, ?list betas, ?string workspaceID): TunnelCertificate` **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 - `tunnelID: string` (path parameter) ID of the tunnel (`tnl_...`). - `certificateID: string` (path parameter) ID of the certificate to archive (`tcrt_...`). - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `mcp-tunnels-2026-06-22` in this header. - `workspaceID?: 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 - `class TunnelCertificate` - `"tunnel_certificate" type` - `string id` Unique identifier for the certificate, prefixed with `tcrt_`. - `?\Datetime archivedAt` RFC 3339 datetime string indicating when the certificate was archived. Null if it is still in the trusted set. - `\Datetime createdAt` RFC 3339 datetime string indicating when the certificate was registered. - `?\Datetime expiresAt` RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire. - `string fingerprint` Lowercase hex SHA-256 fingerprint of the certificate's DER encoding. - `string tunnelID` ID of the tunnel the certificate is registered against. #### Example ```php beta->tunnels->certificates->archive( 'certificate_id', tunnelID: 'tunnel_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaTunnelCertificate); ``` ##### 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 `$client->beta->organization->retrieve(): BetaOrganization` **GET** `/v1/organizations/me` Retrieve information about the organization associated with the authenticated API key. #### Returns - `class BetaOrganization` - `"organization" type` Object type. For Organizations, this is always `"organization"`. - `string id` ID of the Organization. - `string name` Name of the Organization. #### Example ```php beta->organization->retrieve(); var_dump($betaOrganization); ``` ##### Response (200) ```json { "id": "12345678-1234-5678-1234-567812345678", "name": "Organization Name", "type": "organization" } ``` ## Beta › Organization › API Keys ### List API Keys `$client->beta->organization->apiKeys->list(?string afterID, ?string beforeID, ?string createdByUserID, ?int limit, ?Status status, ?string workspaceID): Page` **GET** `/v1/organizations/api_keys` List API Keys #### Parameters - `afterID?: 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. - `beforeID?: 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. - `createdByUserID?: optional string` (query parameter) Filter by the ID of the User who created the object. - `limit?: optional int` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. default: 20 - `status?: optional Status` (query parameter) Filter by API key status. - `workspaceID?: optional string` (query parameter) Filter by Workspace ID. #### Returns - `class APIKey` - `"api_key" type` Object type. For API Keys, this is always `"api_key"`. - `string id` ID of the API key. - `\Datetime createdAt` RFC 3339 datetime string indicating when the API Key was created. - `?APIKeyCreatedBy createdBy` 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). - `?\Datetime expiresAt` RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires. - `string name` Name of the API key. - `?string partialKeyHint` Partially redacted hint for the API key. - `?Principal principal` 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. - `Scope scope` 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. - `Status status` Status of the API key. #### Example ```php beta->organization->apiKeys->list( afterID: 'after_id', beforeID: 'before_id', createdByUserID: 'created_by_user_id', limit: 1, status: 'active', workspaceID: 'workspace_id', ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "id": "apikey_01Rj2N8SVvo6BePZj99NhmiT", "created_at": "2024-10-30T23:58:27.427722Z", "created_by": { "id": "user_01WxYzAbCdEfGhJkMnPqRsTu", "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_01WxYzAbCdEfGhJkMnPqRsTu" }, "scope": { "type": "workspace", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" }, "status": "active", "type": "api_key" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id" } ``` ### Retrieve API Key (Admin API) `$client->beta->organization->apiKeys->retrieve(string apiKeyID): APIKey` **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 - `apiKeyID: string` (path parameter) ID of the API key. #### Returns - `class APIKey` - `"api_key" type` Object type. For API Keys, this is always `"api_key"`. - `string id` ID of the API key. - `\Datetime createdAt` RFC 3339 datetime string indicating when the API Key was created. - `?APIKeyCreatedBy createdBy` 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). - `?\Datetime expiresAt` RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires. - `string name` Name of the API key. - `?string partialKeyHint` Partially redacted hint for the API key. - `?Principal principal` 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. - `Scope scope` 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. - `Status status` Status of the API key. #### Example ```php beta->organization->apiKeys->retrieve('api_key_id'); var_dump($betaAPIKey); ``` ##### Response (200) ```json { "id": "apikey_01Rj2N8SVvo6BePZj99NhmiT", "created_at": "2024-10-30T23:58:27.427722Z", "created_by": { "id": "user_01WxYzAbCdEfGhJkMnPqRsTu", "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_01WxYzAbCdEfGhJkMnPqRsTu" }, "scope": { "type": "workspace", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" }, "status": "active", "type": "api_key" } ``` ### Update API Key `$client->beta->organization->apiKeys->update(string apiKeyID, ?string name, ?Status status): APIKey` **POST** `/v1/organizations/api_keys/{api_key_id}` Update API Key #### Parameters - `apiKeyID: string` (path parameter) ID of the API key. - `name?: optional string` Name of the API key. - `status?: optional Status` Status of the API key. #### Returns - `class APIKey` - `"api_key" type` Object type. For API Keys, this is always `"api_key"`. - `string id` ID of the API key. - `\Datetime createdAt` RFC 3339 datetime string indicating when the API Key was created. - `?APIKeyCreatedBy createdBy` 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). - `?\Datetime expiresAt` RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires. - `string name` Name of the API key. - `?string partialKeyHint` Partially redacted hint for the API key. - `?Principal principal` 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. - `Scope scope` 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. - `Status status` Status of the API key. #### Example ```php beta->organization->apiKeys->update( 'api_key_id', name: 'x', status: 'active' ); var_dump($betaAPIKey); ``` ##### Response (200) ```json { "id": "apikey_01Rj2N8SVvo6BePZj99NhmiT", "created_at": "2024-10-30T23:58:27.427722Z", "created_by": { "id": "user_01WxYzAbCdEfGhJkMnPqRsTu", "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_01WxYzAbCdEfGhJkMnPqRsTu" }, "scope": { "type": "workspace", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" }, "status": "active", "type": "api_key" } ``` ## Beta › Organization › External Keys ### Create External Key `$client->beta->organization->externalKeys->create(ProviderConfig providerConfig, ?string displayName, ?Geo geo, ?string userProfileID): ExternalKey` **POST** `/v1/organizations/external_keys` Create an external key config owned by the caller's organization. #### Parameters - `providerConfig: ProviderConfig` KMS provider identity and auth coordinates. - `displayName?: optional string` Human-friendly display name. - `geo?: optional Geo` Data residency geo. Only `us` is supported. - `userProfileID?: optional string` ID of a user profile to bind the key to. Omit this field for a key that isn't bound to a user profile. Such a key can be attached to a Workspace whatever its user profile. The binding cannot be changed later. A key bound to a user profile can only be attached to a Workspace that has the same user profile. #### Returns - `class ExternalKey` - `"external_key" type` - `string id` Identifier of the external key config: a tagged ID prefixed `ekey_`, or, on Claude Platform on AWS, an AWS KMS key's ARN. - `Attachment attachment` 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. - `\Datetime createdAt` - `?string displayName` Human-friendly display name. Null if none was set. - `string geo` Data residency geo. Selects the region this key is used in. - `ProviderConfig providerConfig` KMS provider identity and auth coordinates. - `\Datetime updatedAt` - `?string userProfileID` ID of the user profile the key is bound to, or null if the key is not bound to one. A key bound to a user profile can only be attached to a Workspace that has the same user profile. A key that isn't bound can be attached to a Workspace whatever its user profile. #### Example ```php beta->organization->externalKeys->create( providerConfig: [ 'kmsARN' => 'arn:aws:kms:us-east-1:111122223333:key/abcd1234-5678-90ab-cdef-000011112222', 'type' => 'aws', 'region' => 'us-east-1', 'roleARN' => 'arn:aws:iam::111122223333:role/anthropic-cmek', ], displayName: 'x', geo: 'us', userProfileID: 'uprof_01SDCCSbTxrXDpWc1phhtcfK', ); var_dump($betaExternalKey); ``` ##### 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", "user_profile_id": "uprof_01SDCCSbTxrXDpWc1phhtcfK" } ``` ### List External Keys `$client->beta->organization->externalKeys->list(?int limit, ?string page): PageCursor` **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 int` (query parameter) Number of results per page. default: 20 - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. #### Returns - `class ExternalKey` - `"external_key" type` - `string id` Identifier of the external key config: a tagged ID prefixed `ekey_`, or, on Claude Platform on AWS, an AWS KMS key's ARN. - `Attachment attachment` 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. - `\Datetime createdAt` - `?string displayName` Human-friendly display name. Null if none was set. - `string geo` Data residency geo. Selects the region this key is used in. - `ProviderConfig providerConfig` KMS provider identity and auth coordinates. - `\Datetime updatedAt` - `?string userProfileID` ID of the user profile the key is bound to, or null if the key is not bound to one. A key bound to a user profile can only be attached to a Workspace that has the same user profile. A key that isn't bound can be attached to a Workspace whatever its user profile. #### Example ```php beta->organization->externalKeys->list(limit: 1, page: 'page'); var_dump($page); ``` ##### 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", "user_profile_id": "uprof_01SDCCSbTxrXDpWc1phhtcfK" } ], "next_page": "next_page" } ``` ### Get External Key `$client->beta->organization->externalKeys->retrieve(string externalKeyID): ExternalKey` **GET** `/v1/organizations/external_keys/{external_key_id}` Retrieve a single external key config in the caller's organization by ID. #### Parameters - `externalKeyID: string` (path parameter) ID of the External Key. #### Returns - `class ExternalKey` - `"external_key" type` - `string id` Identifier of the external key config: a tagged ID prefixed `ekey_`, or, on Claude Platform on AWS, an AWS KMS key's ARN. - `Attachment attachment` 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. - `\Datetime createdAt` - `?string displayName` Human-friendly display name. Null if none was set. - `string geo` Data residency geo. Selects the region this key is used in. - `ProviderConfig providerConfig` KMS provider identity and auth coordinates. - `\Datetime updatedAt` - `?string userProfileID` ID of the user profile the key is bound to, or null if the key is not bound to one. A key bound to a user profile can only be attached to a Workspace that has the same user profile. A key that isn't bound can be attached to a Workspace whatever its user profile. #### Example ```php beta->organization->externalKeys->retrieve( 'external_key_id' ); var_dump($betaExternalKey); ``` ##### 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", "user_profile_id": "uprof_01SDCCSbTxrXDpWc1phhtcfK" } ``` ### Update External Key `$client->beta->organization->externalKeys->update(string externalKeyID, ?string displayName, ?Geo geo, ?ProviderConfig providerConfig): ExternalKey` **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 - `externalKeyID: string` (path parameter) ID of the External Key. - `displayName?: optional string` Human-friendly display name. - `geo?: optional Geo` Data residency geo. Only `us` is supported. - `providerConfig?: optional ProviderConfig` KMS provider identity and auth coordinates. #### Returns - `class ExternalKey` - `"external_key" type` - `string id` Identifier of the external key config: a tagged ID prefixed `ekey_`, or, on Claude Platform on AWS, an AWS KMS key's ARN. - `Attachment attachment` 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. - `\Datetime createdAt` - `?string displayName` Human-friendly display name. Null if none was set. - `string geo` Data residency geo. Selects the region this key is used in. - `ProviderConfig providerConfig` KMS provider identity and auth coordinates. - `\Datetime updatedAt` - `?string userProfileID` ID of the user profile the key is bound to, or null if the key is not bound to one. A key bound to a user profile can only be attached to a Workspace that has the same user profile. A key that isn't bound can be attached to a Workspace whatever its user profile. #### Example ```php beta->organization->externalKeys->update( 'external_key_id', displayName: 'x', geo: 'us', providerConfig: [ 'kmsARN' => 'arn:aws:kms:us-east-1:111122223333:key/abcd1234-5678-90ab-cdef-000011112222', 'type' => 'aws', 'region' => 'us-east-1', 'roleARN' => 'arn:aws:iam::111122223333:role/anthropic-cmek', ], ); var_dump($betaExternalKey); ``` ##### 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", "user_profile_id": "uprof_01SDCCSbTxrXDpWc1phhtcfK" } ``` ### Delete External Key `$client->beta->organization->externalKeys->delete(string externalKeyID): ExternalKeyDeleteResponse` **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 - `externalKeyID: string` (path parameter) ID of the External Key. #### Returns - `class ExternalKeyDeleteResponse` - `"external_key_deleted" type` - `string id` ID of the deleted External Key. #### Example ```php beta->organization->externalKeys->delete( 'external_key_id' ); var_dump($externalKey); ``` ##### Response (200) ```json { "id": "ekey_01AbCdEfGhIjKlMnOpQrStUv", "type": "external_key_deleted" } ``` ### Validate External Key `$client->beta->organization->externalKeys->validate(string externalKeyID): ExternalKeyValidateResponse` **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 - `externalKeyID: string` (path parameter) ID of the External Key. #### Returns - `class ExternalKeyValidateResponse` - `"external_key_validation" type` - `?string error` Error message when status is `failure`. Null otherwise. - `Status status` `success` — encrypt/decrypt roundtrip succeeded. `failure` — the roundtrip failed or timed out; see `error`. #### Example ```php beta->organization->externalKeys->validate( 'external_key_id' ); var_dump($response); ``` ##### Response (200) ```json { "error": "error", "status": "failure", "type": "external_key_validation" } ``` ## Beta › Organization › Federation › Issuers ### Create Federation Issuer `$client->beta->organization->federation->issuers->create(string issuerURL, string name, ?bool checkJTI, ?JWKS jwks, ?int maxJWTLifetimeSeconds, ?list betas): BetaFederationIssuer` **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=php). 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 - `issuerURL: string` The `iss` claim value to match against. - `name: string` Slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409. - `checkJTI?: optional bool` 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 JWKS` How signing keys are obtained. Defaults to OIDC discovery. - `maxJWTLifetimeSeconds?: optional int` 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. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class BetaFederationIssuer` - `"federation_issuer" type` - `string id` Tagged ID of the federation issuer. - `?\Datetime archivedAt` If set, all rules referencing this issuer reject token exchange. - `?string archivedByActorID` Tagged ID (`user_`/`svac_`) of the actor that archived this issuer. - `bool checkJTI` 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. - `\Datetime createdAt` When this issuer was created. - `?string createdByActorID` Tagged ID (`user_`/`svac_`) of the actor that created this issuer. - `string issuerURL` The `iss` claim value. Incoming JWTs must match exactly. - `JWKS jwks` How signing keys are obtained for signature verification. - `?\Datetime jwksPollingDisabledAt` 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. - `int maxJWTLifetimeSeconds` 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. - `string name` Admin-chosen slug identifier. - `?BetaFederationIssuerPollStatus pollStatus` 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. - `\Datetime updatedAt` When this issuer was last updated. - `?string updatedByActorID` Tagged ID (`user_`/`svac_`) of the actor that last updated this issuer. #### Example ```php beta ->organization ->federation ->issuers ->create( issuerURL: 'x', name: 'x', checkJTI: true, jwks: [ 'type' => 'discovery', 'caCertPEM' => 'ca_cert_pem', 'discoveryBase' => 'discovery_base', ], maxJWTLifetimeSeconds: 1, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaFederationIssuer); ``` ##### 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 `$client->beta->organization->federation->issuers->list(?bool includeArchived, ?int limit, ?string page, ?list betas): PageCursor` **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=php). List federation issuers in your organization. Archived issuers are excluded unless `include_archived=true`. #### Parameters - `includeArchived?: optional bool` (query parameter) Include archived resources. Defaults to false. default: false - `limit?: optional int` (query parameter) Number of results per page. default: 20 - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class BetaFederationIssuer` - `"federation_issuer" type` - `string id` Tagged ID of the federation issuer. - `?\Datetime archivedAt` If set, all rules referencing this issuer reject token exchange. - `?string archivedByActorID` Tagged ID (`user_`/`svac_`) of the actor that archived this issuer. - `bool checkJTI` 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. - `\Datetime createdAt` When this issuer was created. - `?string createdByActorID` Tagged ID (`user_`/`svac_`) of the actor that created this issuer. - `string issuerURL` The `iss` claim value. Incoming JWTs must match exactly. - `JWKS jwks` How signing keys are obtained for signature verification. - `?\Datetime jwksPollingDisabledAt` 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. - `int maxJWTLifetimeSeconds` 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. - `string name` Admin-chosen slug identifier. - `?BetaFederationIssuerPollStatus pollStatus` 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. - `\Datetime updatedAt` When this issuer was last updated. - `?string updatedByActorID` Tagged ID (`user_`/`svac_`) of the actor that last updated this issuer. #### Example ```php beta->organization->federation->issuers->list( includeArchived: true, limit: 1, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### 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 `$client->beta->organization->federation->issuers->retrieve(string federationIssuerID, ?list betas): BetaFederationIssuer` **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=php). Retrieve a federation issuer by its ID (`fdis_...`). #### Parameters - `federationIssuerID: string` (path parameter) ID of the federation issuer. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class BetaFederationIssuer` - `"federation_issuer" type` - `string id` Tagged ID of the federation issuer. - `?\Datetime archivedAt` If set, all rules referencing this issuer reject token exchange. - `?string archivedByActorID` Tagged ID (`user_`/`svac_`) of the actor that archived this issuer. - `bool checkJTI` 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. - `\Datetime createdAt` When this issuer was created. - `?string createdByActorID` Tagged ID (`user_`/`svac_`) of the actor that created this issuer. - `string issuerURL` The `iss` claim value. Incoming JWTs must match exactly. - `JWKS jwks` How signing keys are obtained for signature verification. - `?\Datetime jwksPollingDisabledAt` 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. - `int maxJWTLifetimeSeconds` 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. - `string name` Admin-chosen slug identifier. - `?BetaFederationIssuerPollStatus pollStatus` 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. - `\Datetime updatedAt` When this issuer was last updated. - `?string updatedByActorID` Tagged ID (`user_`/`svac_`) of the actor that last updated this issuer. #### Example ```php beta ->organization ->federation ->issuers ->retrieve( 'federation_issuer_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24] ); var_dump($betaFederationIssuer); ``` ##### 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 `$client->beta->organization->federation->issuers->update(string federationIssuerID, ?bool checkJTI, ?string issuerURL, ?JWKS jwks, ?bool jwksPollingDisabled, ?int maxJWTLifetimeSeconds, ?string name, ?list betas): BetaFederationIssuer` **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=php). 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 - `federationIssuerID: string` (path parameter) ID of the federation issuer to update. - `checkJTI?: optional bool` 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. - `issuerURL?: 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. - `jwks?: optional JWKS` Replaces the entire JWKS configuration. - `jwksPollingDisabled?: optional bool` Only `false` is accepted, to re-enable polling after the system pauses it. Polling is paused automatically; sending `true` is rejected. - `maxJWTLifetimeSeconds?: optional int` 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?: optional string` Replaces the slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class BetaFederationIssuer` - `"federation_issuer" type` - `string id` Tagged ID of the federation issuer. - `?\Datetime archivedAt` If set, all rules referencing this issuer reject token exchange. - `?string archivedByActorID` Tagged ID (`user_`/`svac_`) of the actor that archived this issuer. - `bool checkJTI` 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. - `\Datetime createdAt` When this issuer was created. - `?string createdByActorID` Tagged ID (`user_`/`svac_`) of the actor that created this issuer. - `string issuerURL` The `iss` claim value. Incoming JWTs must match exactly. - `JWKS jwks` How signing keys are obtained for signature verification. - `?\Datetime jwksPollingDisabledAt` 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. - `int maxJWTLifetimeSeconds` 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. - `string name` Admin-chosen slug identifier. - `?BetaFederationIssuerPollStatus pollStatus` 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. - `\Datetime updatedAt` When this issuer was last updated. - `?string updatedByActorID` Tagged ID (`user_`/`svac_`) of the actor that last updated this issuer. #### Example ```php beta ->organization ->federation ->issuers ->update( 'federation_issuer_id', checkJTI: true, issuerURL: 'x', jwks: [ 'type' => 'discovery', 'caCertPEM' => 'ca_cert_pem', 'discoveryBase' => 'discovery_base', ], jwksPollingDisabled: true, maxJWTLifetimeSeconds: 1, name: 'x', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaFederationIssuer); ``` ##### 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 `$client->beta->organization->federation->issuers->archive(string federationIssuerID, ?list betas): BetaFederationIssuer` **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=php). 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 - `federationIssuerID: string` (path parameter) ID of the federation issuer to archive. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class BetaFederationIssuer` - `"federation_issuer" type` - `string id` Tagged ID of the federation issuer. - `?\Datetime archivedAt` If set, all rules referencing this issuer reject token exchange. - `?string archivedByActorID` Tagged ID (`user_`/`svac_`) of the actor that archived this issuer. - `bool checkJTI` 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. - `\Datetime createdAt` When this issuer was created. - `?string createdByActorID` Tagged ID (`user_`/`svac_`) of the actor that created this issuer. - `string issuerURL` The `iss` claim value. Incoming JWTs must match exactly. - `JWKS jwks` How signing keys are obtained for signature verification. - `?\Datetime jwksPollingDisabledAt` 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. - `int maxJWTLifetimeSeconds` 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. - `string name` Admin-chosen slug identifier. - `?BetaFederationIssuerPollStatus pollStatus` 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. - `\Datetime updatedAt` When this issuer was last updated. - `?string updatedByActorID` Tagged ID (`user_`/`svac_`) of the actor that last updated this issuer. #### Example ```php beta ->organization ->federation ->issuers ->archive( 'federation_issuer_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24] ); var_dump($betaFederationIssuer); ``` ##### 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 `$client->beta->organization->federation->rules->create(string issuerID, BetaFederationRuleMatch match, string name, string oauthScope, BetaServiceAccountTarget target, ?bool appliesToAllWorkspaces, ?array attributes, ?string description, ?int tokenLifetimeSeconds, ?string workspaceID, ?list betas): BetaFederationRule` **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=php). 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 - `issuerID: string` Tagged ID of the federation issuer. - `match: BetaFederationRuleMatch` 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. - `oauthScope: 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. - `target: BetaServiceAccountTarget` Identity that tokens minted via this rule act as. Currently always a `service_account` target. - `appliesToAllWorkspaces?: optional bool` When true, enable this rule for every workspace in the org (including workspaces created later). - `attributes?: optional array` 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. - `tokenLifetimeSeconds?: optional int` 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. - `workspaceID?: 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. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class BetaFederationRule` - `"federation_rule" type` - `string id` Tagged ID of the federation rule. - `bool appliesToAllWorkspaces` 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. - `?\Datetime archivedAt` If set, this rule is archived and rejects token exchange. - `?string archivedByActorID` Tagged ID (`user_`/`svac_`) of the actor that archived this rule. - `?array attributes` CEL expressions extracting named values from claims. Not yet supported; always null. - `\Datetime createdAt` When this rule was created. - `?string createdByActorID` Tagged ID (`user_`/`svac_`) of the actor that created this rule. - `?string description` Optional free-text description. - `string issuerID` Tagged ID of the issuer whose tokens this rule accepts. - `?string issuerName` Issuer's display name at read time. - `BetaFederationRuleMatch match` Conditions the verified JWT must satisfy for this rule to apply. All populated matcher fields must pass. - `string name` Admin-chosen slug identifier. - `string oauthScope` Space-separated OAuth scopes granted on the minted token. - `BetaServiceAccountTarget target` 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. - `int tokenLifetimeSeconds` 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. - `\Datetime updatedAt` When this rule was last updated. - `?string updatedByActorID` Tagged ID (`user_`/`svac_`) of the actor that last updated this rule. - `?string workspaceID` Legacy single-workspace binding. Prefer `workspace_ids` and the `/federation_rules/{federation_rule_id}/workspaces` sub-resource for managing workspace enablement. - `list workspaceIDs` 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 ```php beta->organization->federation->rules->create( issuerID: 'issuer_id', match: [ 'audience' => 'audience', 'claims' => ['foo' => 'string'], 'condition' => 'condition', 'subjectPrefix' => 'subject_prefix', ], name: 'x', oauthScope: 'x', target: [ 'serviceAccountID' => 'svac_01SDCCSbTxrXDpWc1phhtcfK', 'type' => 'service_account', 'serviceAccountName' => 'service_account_name', ], appliesToAllWorkspaces: true, attributes: ['foo' => 'string'], description: 'description', tokenLifetimeSeconds: 60, workspaceID: 'workspace_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaFederationRule); ``` ##### 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 `$client->beta->organization->federation->rules->list(?bool includeArchived, ?string issuerID, ?int limit, ?string page, ?list betas): PageCursor` **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=php). List federation rules in your organization. Optionally filter by issuer with `issuer_id`. Archived rules are excluded unless `include_archived=true`. #### Parameters - `includeArchived?: optional bool` (query parameter) Include archived resources. Defaults to false. default: false - `issuerID?: optional string` (query parameter) Filter to rules referencing this federation issuer. - `limit?: optional int` (query parameter) Number of results per page. default: 20 - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class BetaFederationRule` - `"federation_rule" type` - `string id` Tagged ID of the federation rule. - `bool appliesToAllWorkspaces` 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. - `?\Datetime archivedAt` If set, this rule is archived and rejects token exchange. - `?string archivedByActorID` Tagged ID (`user_`/`svac_`) of the actor that archived this rule. - `?array attributes` CEL expressions extracting named values from claims. Not yet supported; always null. - `\Datetime createdAt` When this rule was created. - `?string createdByActorID` Tagged ID (`user_`/`svac_`) of the actor that created this rule. - `?string description` Optional free-text description. - `string issuerID` Tagged ID of the issuer whose tokens this rule accepts. - `?string issuerName` Issuer's display name at read time. - `BetaFederationRuleMatch match` Conditions the verified JWT must satisfy for this rule to apply. All populated matcher fields must pass. - `string name` Admin-chosen slug identifier. - `string oauthScope` Space-separated OAuth scopes granted on the minted token. - `BetaServiceAccountTarget target` 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. - `int tokenLifetimeSeconds` 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. - `\Datetime updatedAt` When this rule was last updated. - `?string updatedByActorID` Tagged ID (`user_`/`svac_`) of the actor that last updated this rule. - `?string workspaceID` Legacy single-workspace binding. Prefer `workspace_ids` and the `/federation_rules/{federation_rule_id}/workspaces` sub-resource for managing workspace enablement. - `list workspaceIDs` 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 ```php beta->organization->federation->rules->list( includeArchived: true, issuerID: 'issuer_id', limit: 1, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### 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 `$client->beta->organization->federation->rules->retrieve(string federationRuleID, ?list betas): BetaFederationRule` **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=php). Retrieve a federation rule by its ID (`fdrl_...`). #### Parameters - `federationRuleID: string` (path parameter) ID of the federation rule. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class BetaFederationRule` - `"federation_rule" type` - `string id` Tagged ID of the federation rule. - `bool appliesToAllWorkspaces` 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. - `?\Datetime archivedAt` If set, this rule is archived and rejects token exchange. - `?string archivedByActorID` Tagged ID (`user_`/`svac_`) of the actor that archived this rule. - `?array attributes` CEL expressions extracting named values from claims. Not yet supported; always null. - `\Datetime createdAt` When this rule was created. - `?string createdByActorID` Tagged ID (`user_`/`svac_`) of the actor that created this rule. - `?string description` Optional free-text description. - `string issuerID` Tagged ID of the issuer whose tokens this rule accepts. - `?string issuerName` Issuer's display name at read time. - `BetaFederationRuleMatch match` Conditions the verified JWT must satisfy for this rule to apply. All populated matcher fields must pass. - `string name` Admin-chosen slug identifier. - `string oauthScope` Space-separated OAuth scopes granted on the minted token. - `BetaServiceAccountTarget target` 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. - `int tokenLifetimeSeconds` 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. - `\Datetime updatedAt` When this rule was last updated. - `?string updatedByActorID` Tagged ID (`user_`/`svac_`) of the actor that last updated this rule. - `?string workspaceID` Legacy single-workspace binding. Prefer `workspace_ids` and the `/federation_rules/{federation_rule_id}/workspaces` sub-resource for managing workspace enablement. - `list workspaceIDs` 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 ```php beta->organization->federation->rules->retrieve( 'federation_rule_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24] ); var_dump($betaFederationRule); ``` ##### 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 `$client->beta->organization->federation->rules->update(string federationRuleID, ?bool appliesToAllWorkspaces, ?array attributes, ?string description, ?BetaFederationRuleMatch match, ?string name, ?string oauthScope, ?BetaServiceAccountTarget target, ?int tokenLifetimeSeconds, ?string workspaceID, ?list betas): BetaFederationRule` **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=php). 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 - `federationRuleID: string` (path parameter) ID of the federation rule to update. - `appliesToAllWorkspaces?: optional bool` 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 array` 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). - `match?: optional BetaFederationRuleMatch` 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. - `oauthScope?: 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. - `target?: optional BetaServiceAccountTarget` Replaces the entire target object. Currently always a `service_account` target. - `tokenLifetimeSeconds?: optional int` 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. - `workspaceID?: 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. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class BetaFederationRule` - `"federation_rule" type` - `string id` Tagged ID of the federation rule. - `bool appliesToAllWorkspaces` 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. - `?\Datetime archivedAt` If set, this rule is archived and rejects token exchange. - `?string archivedByActorID` Tagged ID (`user_`/`svac_`) of the actor that archived this rule. - `?array attributes` CEL expressions extracting named values from claims. Not yet supported; always null. - `\Datetime createdAt` When this rule was created. - `?string createdByActorID` Tagged ID (`user_`/`svac_`) of the actor that created this rule. - `?string description` Optional free-text description. - `string issuerID` Tagged ID of the issuer whose tokens this rule accepts. - `?string issuerName` Issuer's display name at read time. - `BetaFederationRuleMatch match` Conditions the verified JWT must satisfy for this rule to apply. All populated matcher fields must pass. - `string name` Admin-chosen slug identifier. - `string oauthScope` Space-separated OAuth scopes granted on the minted token. - `BetaServiceAccountTarget target` 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. - `int tokenLifetimeSeconds` 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. - `\Datetime updatedAt` When this rule was last updated. - `?string updatedByActorID` Tagged ID (`user_`/`svac_`) of the actor that last updated this rule. - `?string workspaceID` Legacy single-workspace binding. Prefer `workspace_ids` and the `/federation_rules/{federation_rule_id}/workspaces` sub-resource for managing workspace enablement. - `list workspaceIDs` 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 ```php beta->organization->federation->rules->update( 'federation_rule_id', appliesToAllWorkspaces: true, attributes: ['foo' => 'string'], description: 'description', match: [ 'audience' => 'audience', 'claims' => ['foo' => 'string'], 'condition' => 'condition', 'subjectPrefix' => 'subject_prefix', ], name: 'x', oauthScope: 'x', target: [ 'serviceAccountID' => 'svac_01SDCCSbTxrXDpWc1phhtcfK', 'type' => 'service_account', 'serviceAccountName' => 'service_account_name', ], tokenLifetimeSeconds: 60, workspaceID: 'workspace_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaFederationRule); ``` ##### 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 `$client->beta->organization->federation->rules->archive(string federationRuleID, ?list betas): BetaFederationRule` **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=php). 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 - `federationRuleID: string` (path parameter) ID of the federation rule to archive. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class BetaFederationRule` - `"federation_rule" type` - `string id` Tagged ID of the federation rule. - `bool appliesToAllWorkspaces` 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. - `?\Datetime archivedAt` If set, this rule is archived and rejects token exchange. - `?string archivedByActorID` Tagged ID (`user_`/`svac_`) of the actor that archived this rule. - `?array attributes` CEL expressions extracting named values from claims. Not yet supported; always null. - `\Datetime createdAt` When this rule was created. - `?string createdByActorID` Tagged ID (`user_`/`svac_`) of the actor that created this rule. - `?string description` Optional free-text description. - `string issuerID` Tagged ID of the issuer whose tokens this rule accepts. - `?string issuerName` Issuer's display name at read time. - `BetaFederationRuleMatch match` Conditions the verified JWT must satisfy for this rule to apply. All populated matcher fields must pass. - `string name` Admin-chosen slug identifier. - `string oauthScope` Space-separated OAuth scopes granted on the minted token. - `BetaServiceAccountTarget target` 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. - `int tokenLifetimeSeconds` 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. - `\Datetime updatedAt` When this rule was last updated. - `?string updatedByActorID` Tagged ID (`user_`/`svac_`) of the actor that last updated this rule. - `?string workspaceID` Legacy single-workspace binding. Prefer `workspace_ids` and the `/federation_rules/{federation_rule_id}/workspaces` sub-resource for managing workspace enablement. - `list workspaceIDs` 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 ```php beta->organization->federation->rules->archive( 'federation_rule_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24] ); var_dump($betaFederationRule); ``` ##### 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 `$client->beta->organization->federation->rules->workspaces->add(string federationRuleID, string workspaceID, ?list betas): BetaFederationRuleWorkspace` **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=php). 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 - `federationRuleID: string` (path parameter) ID of the federation rule. - `workspaceID: string` Tagged ID of the workspace to enable this rule for. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class BetaFederationRuleWorkspace` - `"federation_rule_workspace" type` - `\Datetime createdAt` When this workspace was enabled for the rule. - `?string createdByActorID` Tagged ID (`user_...` or `svac_...`) of the actor that enabled this workspace for the rule, if known. - `string federationRuleID` Tagged ID of the federation rule. - `string workspaceID` Tagged ID of the workspace this rule is enabled for. - `?string workspaceName` Workspace display name. Populated when listing; null in the enable response. #### Example ```php beta ->organization ->federation ->rules ->workspaces ->add( 'federation_rule_id', workspaceID: 'workspace_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaFederationRuleWorkspace); ``` ##### 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 `$client->beta->organization->federation->rules->workspaces->list(string federationRuleID, ?int limit, ?string page, ?list betas): PageCursor` **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=php). 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 - `federationRuleID: string` (path parameter) ID of the federation rule. - `limit?: optional int` (query parameter) Number of results per page. default: 20 - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class BetaFederationRuleWorkspace` - `"federation_rule_workspace" type` - `\Datetime createdAt` When this workspace was enabled for the rule. - `?string createdByActorID` Tagged ID (`user_...` or `svac_...`) of the actor that enabled this workspace for the rule, if known. - `string federationRuleID` Tagged ID of the federation rule. - `string workspaceID` Tagged ID of the workspace this rule is enabled for. - `?string workspaceName` Workspace display name. Populated when listing; null in the enable response. #### Example ```php beta->organization->federation->rules->workspaces->list( 'federation_rule_id', limit: 1, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### 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 `$client->beta->organization->federation->rules->workspaces->remove(string workspaceID, string federationRuleID, ?list betas): WorkspaceRemoveResponse` **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=php). 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 - `federationRuleID: string` (path parameter) ID of the federation rule. - `workspaceID: string` (path parameter) ID of the workspace to disable for. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class WorkspaceRemoveResponse` - `"federation_rule_workspace_deleted" type` - `string federationRuleID` Tagged ID of the federation rule. - `string workspaceID` Tagged ID of the workspace named in the delete request. Removal is idempotent. #### Example ```php beta->organization->federation->rules->workspaces->remove( 'workspace_id', federationRuleID: 'federation_rule_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($workspace); ``` ##### Response (200) ```json { "federation_rule_id": "federation_rule_id", "type": "federation_rule_workspace_deleted", "workspace_id": "workspace_id" } ``` ## Beta › Organization › Invites ### Create Invite `$client->beta->organization->invites->create(string email, Role role, ?list rbacGroupIDs): OrganizationInvite` **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. - `role: Role` 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`. - `rbacGroupIDs?: optional list` 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. #### Returns - `class OrganizationInvite` - `"invite" type` Object type. For Invites, this is always `"invite"`. - `string id` ID of the Invite. - `?\Datetime acceptedAt` RFC 3339 datetime string indicating when the Invite was accepted, or null. - `string email` Email of the User being invited. - `\Datetime expiresAt` RFC 3339 datetime string indicating when the Invite expires. - `\Datetime invitedAt` RFC 3339 datetime string indicating when the Invite was created. - `list rbacGroupIDs` RBAC group IDs recorded on the Invite (Claude Enterprise organizations), to be assigned to the User when the Invite is accepted. `[]` when none. - `BetaOrganizationRole role` Organization role of the User. - `Status status` Status of the Invite. #### Example ```php beta->organization->invites->create( email: 'user@emaildomain.com', role: 'user', rbacGroupIDs: ['string'] ); var_dump($betaOrganizationInvite); ``` ##### 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 `$client->beta->organization->invites->list(?string afterID, ?string beforeID, ?string email, ?int limit, ?list roles, ?list statuses): Page` **GET** `/v1/organizations/invites` List the organization's invites. #### Parameters - `afterID?: 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. - `beforeID?: 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). - `limit?: optional int` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. default: 20 - `roles?: optional list` (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`. - `statuses?: optional list` (query parameter) Filter by Invite status. Repeatable; values are OR'ed together. Omit to return `pending`, `accepted`, and `expired` Invites alike. #### Returns - `class OrganizationInvite` - `"invite" type` Object type. For Invites, this is always `"invite"`. - `string id` ID of the Invite. - `?\Datetime acceptedAt` RFC 3339 datetime string indicating when the Invite was accepted, or null. - `string email` Email of the User being invited. - `\Datetime expiresAt` RFC 3339 datetime string indicating when the Invite expires. - `\Datetime invitedAt` RFC 3339 datetime string indicating when the Invite was created. - `list rbacGroupIDs` RBAC group IDs recorded on the Invite (Claude Enterprise organizations), to be assigned to the User when the Invite is accepted. `[]` when none. - `BetaOrganizationRole role` Organization role of the User. - `Status status` Status of the Invite. #### Example ```php beta->organization->invites->list( afterID: 'after_id', beforeID: 'before_id', email: 'dev@stainless.com', limit: 1, roles: ['string'], statuses: ['accepted'], ); var_dump($page); ``` ##### 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 `$client->beta->organization->invites->retrieve(string inviteID): OrganizationInvite` **GET** `/v1/organizations/invites/{invite_id}` Retrieve an invite by ID. #### Parameters - `inviteID: string` (path parameter) ID of the Invite. #### Returns - `class OrganizationInvite` - `"invite" type` Object type. For Invites, this is always `"invite"`. - `string id` ID of the Invite. - `?\Datetime acceptedAt` RFC 3339 datetime string indicating when the Invite was accepted, or null. - `string email` Email of the User being invited. - `\Datetime expiresAt` RFC 3339 datetime string indicating when the Invite expires. - `\Datetime invitedAt` RFC 3339 datetime string indicating when the Invite was created. - `list rbacGroupIDs` RBAC group IDs recorded on the Invite (Claude Enterprise organizations), to be assigned to the User when the Invite is accepted. `[]` when none. - `BetaOrganizationRole role` Organization role of the User. - `Status status` Status of the Invite. #### Example ```php beta->organization->invites->retrieve( 'invite_id' ); var_dump($betaOrganizationInvite); ``` ##### 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 `$client->beta->organization->invites->delete(string inviteID): InviteDeleteResponse` **DELETE** `/v1/organizations/invites/{invite_id}` Delete a pending invite. #### Parameters - `inviteID: string` (path parameter) ID of the Invite. #### Returns - `class InviteDeleteResponse` - `"invite_deleted" type` Deleted object type. For Invites, this is always `"invite_deleted"`. - `string id` ID of the Invite. #### Example ```php beta->organization->invites->delete('invite_id'); var_dump($invite); ``` ##### Response (200) ```json { "id": "invite_015gWxCN9Hfg2QhZwTK7Mdeu", "type": "invite_deleted" } ``` ## Beta › Organization › Service Accounts ### Create Service Account `$client->beta->organization->serviceAccounts->create(string name, ?string description, ?OrganizationRole organizationRole, ?list betas): ServiceAccount` **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=php). 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. - `description?: optional string` Optional free-text description. - `organizationRole?: optional OrganizationRole` Org-level role. Defaults to `developer`. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class ServiceAccount` - `"service_account" type` - `string id` Tagged ID of the service account. - `?\Datetime archivedAt` If set, this service account is archived. - `?string archivedByActorID` Tagged ID (`user_`/`svac_`) of the actor that archived this service account. - `\Datetime createdAt` When this service account was created. - `?string createdByActorID` Tagged ID (`user_`/`svac_`) of the actor that created this service account. - `?string description` Optional free-text description. - `string name` Admin-chosen slug identifier. - `OrganizationRole organizationRole` 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. - `\Datetime updatedAt` When this service account was last updated. - `?string updatedByActorID` Tagged ID (`user_`/`svac_`) of the actor that last updated this service account. #### Example ```php beta->organization->serviceAccounts->create( name: 'ci-deploy-bot', description: 'description', organizationRole: 'admin', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaServiceAccount); ``` ##### 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 `$client->beta->organization->serviceAccounts->list(?bool includeArchived, ?int limit, ?string page, ?list betas): PageCursor` **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=php). 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 - `includeArchived?: optional bool` (query parameter) Include archived resources. Defaults to false. default: false - `limit?: optional int` (query parameter) Number of results per page. default: 20 - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class ServiceAccount` - `"service_account" type` - `string id` Tagged ID of the service account. - `?\Datetime archivedAt` If set, this service account is archived. - `?string archivedByActorID` Tagged ID (`user_`/`svac_`) of the actor that archived this service account. - `\Datetime createdAt` When this service account was created. - `?string createdByActorID` Tagged ID (`user_`/`svac_`) of the actor that created this service account. - `?string description` Optional free-text description. - `string name` Admin-chosen slug identifier. - `OrganizationRole organizationRole` 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. - `\Datetime updatedAt` When this service account was last updated. - `?string updatedByActorID` Tagged ID (`user_`/`svac_`) of the actor that last updated this service account. #### Example ```php beta->organization->serviceAccounts->list( includeArchived: true, limit: 1, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### 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 `$client->beta->organization->serviceAccounts->retrieve(string serviceAccountID, ?list betas): ServiceAccount` **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=php). Retrieve a service account by its ID (`svac_...`). #### Parameters - `serviceAccountID: string` (path parameter) ID of the service account. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class ServiceAccount` - `"service_account" type` - `string id` Tagged ID of the service account. - `?\Datetime archivedAt` If set, this service account is archived. - `?string archivedByActorID` Tagged ID (`user_`/`svac_`) of the actor that archived this service account. - `\Datetime createdAt` When this service account was created. - `?string createdByActorID` Tagged ID (`user_`/`svac_`) of the actor that created this service account. - `?string description` Optional free-text description. - `string name` Admin-chosen slug identifier. - `OrganizationRole organizationRole` 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. - `\Datetime updatedAt` When this service account was last updated. - `?string updatedByActorID` Tagged ID (`user_`/`svac_`) of the actor that last updated this service account. #### Example ```php beta->organization->serviceAccounts->retrieve( 'service_account_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24] ); var_dump($betaServiceAccount); ``` ##### 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 `$client->beta->organization->serviceAccounts->update(string serviceAccountID, ?string description, ?OrganizationRole organizationRole, ?list betas): ServiceAccount` **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=php). 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 - `serviceAccountID: 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). - `organizationRole?: optional OrganizationRole` Replaces the org-level role. Omit or send `null` to leave unchanged. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class ServiceAccount` - `"service_account" type` - `string id` Tagged ID of the service account. - `?\Datetime archivedAt` If set, this service account is archived. - `?string archivedByActorID` Tagged ID (`user_`/`svac_`) of the actor that archived this service account. - `\Datetime createdAt` When this service account was created. - `?string createdByActorID` Tagged ID (`user_`/`svac_`) of the actor that created this service account. - `?string description` Optional free-text description. - `string name` Admin-chosen slug identifier. - `OrganizationRole organizationRole` 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. - `\Datetime updatedAt` When this service account was last updated. - `?string updatedByActorID` Tagged ID (`user_`/`svac_`) of the actor that last updated this service account. #### Example ```php beta->organization->serviceAccounts->update( 'service_account_id', description: 'description', organizationRole: 'admin', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaServiceAccount); ``` ##### 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 `$client->beta->organization->serviceAccounts->archive(string serviceAccountID, ?list betas): ServiceAccount` **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=php). 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 - `serviceAccountID: string` (path parameter) ID of the service account to archive. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class ServiceAccount` - `"service_account" type` - `string id` Tagged ID of the service account. - `?\Datetime archivedAt` If set, this service account is archived. - `?string archivedByActorID` Tagged ID (`user_`/`svac_`) of the actor that archived this service account. - `\Datetime createdAt` When this service account was created. - `?string createdByActorID` Tagged ID (`user_`/`svac_`) of the actor that created this service account. - `?string description` Optional free-text description. - `string name` Admin-chosen slug identifier. - `OrganizationRole organizationRole` 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. - `\Datetime updatedAt` When this service account was last updated. - `?string updatedByActorID` Tagged ID (`user_`/`svac_`) of the actor that last updated this service account. #### Example ```php beta->organization->serviceAccounts->archive( 'service_account_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24] ); var_dump($betaServiceAccount); ``` ##### 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 `$client->beta->organization->serviceAccounts->workspaces->add(string serviceAccountID, string workspaceID, NoBillingWorkspaceRole workspaceRole, ?list betas): ServiceAccountWorkspaceMember` **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=php). 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 - `serviceAccountID: string` (path parameter) ID of the service account. - `workspaceID: string` Tagged workspace ID to add the service account to. - `workspaceRole: NoBillingWorkspaceRole` Role to assign to the service account in this workspace. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class ServiceAccountWorkspaceMember` - `"service_account_workspace_member" type` - `?string createdByActorID` Tagged ID (`user_...`/`svac_...`) of the actor who created this membership. - `?bool implicit` 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. - `string serviceAccountID` Tagged service account ID (`svac_...`). - `string workspaceID` Tagged workspace ID (`wrkspc_...`). - `WorkspaceRole workspaceRole` Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role. #### Example ```php beta ->organization ->serviceAccounts ->workspaces ->add( 'service_account_id', workspaceID: 'workspace_id', workspaceRole: NoBillingWorkspaceRole::WORKSPACE_ADMIN, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaServiceAccountWorkspaceMember); ``` ##### 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 `$client->beta->organization->serviceAccounts->workspaces->list(string serviceAccountID, ?int limit, ?string page, ?list betas): PageCursor` **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=php). 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 - `serviceAccountID: string` (path parameter) ID of the service account. - `limit?: optional int` (query parameter) Number of results per page. default: 20 - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class ServiceAccountWorkspaceMember` - `"service_account_workspace_member" type` - `?string createdByActorID` Tagged ID (`user_...`/`svac_...`) of the actor who created this membership. - `?bool implicit` 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. - `string serviceAccountID` Tagged service account ID (`svac_...`). - `string workspaceID` Tagged workspace ID (`wrkspc_...`). - `WorkspaceRole workspaceRole` Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role. #### Example ```php beta->organization->serviceAccounts->workspaces->list( 'service_account_id', limit: 1, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### 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 `$client->beta->organization->serviceAccounts->workspaces->remove(string workspaceID, string serviceAccountID, ?list betas): WorkspaceRemoveResponse` **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=php). 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 - `serviceAccountID: string` (path parameter) ID of the service account. - `workspaceID: string` (path parameter) ID of the workspace. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class WorkspaceRemoveResponse` - `"service_account_workspace_member_deleted" type` - `string serviceAccountID` Tagged service account ID (`svac_...`) named in the delete request. Removal is idempotent; see the endpoint description for the implicit-membership no-op. - `string workspaceID` Tagged workspace ID (`wrkspc_...`) named in the delete request. #### Example ```php beta->organization->serviceAccounts->workspaces->remove( 'workspace_id', serviceAccountID: 'service_account_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($workspace); ``` ##### Response (200) ```json { "service_account_id": "service_account_id", "type": "service_account_workspace_member_deleted", "workspace_id": "workspace_id" } ``` ## Beta › Organization › Users ### List Users `$client->beta->organization->users->list(?string afterID, ?string beforeID, ?string email, ?int limit, ?list roles): Page` **GET** `/v1/organizations/users` List the organization's members. #### Parameters - `afterID?: 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. - `beforeID?: 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. - `limit?: optional int` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. default: 20 - `roles?: optional list` (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 - `class OrganizationUser` - `"user" type` Object type. For Users, this is always `"user"`. - `string id` ID of the User. - `\Datetime addedAt` RFC 3339 datetime string indicating when the User joined the Organization. - `string email` Email of the User. - `string name` Name of the User. - `BetaOrganizationRole role` Organization role of the User. #### Example ```php beta->organization->users->list( afterID: 'after_id', beforeID: 'before_id', email: 'dev@stainless.com', limit: 1, roles: ['string'], ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "id": "user_01WxYzAbCdEfGhJkMnPqRsTu", "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 `$client->beta->organization->users->retrieve(string userID): OrganizationUser` **GET** `/v1/organizations/users/{user_id}` Retrieve a member of the organization by user ID. #### Parameters - `userID: string` (path parameter) ID of the User. #### Returns - `class OrganizationUser` - `"user" type` Object type. For Users, this is always `"user"`. - `string id` ID of the User. - `\Datetime addedAt` RFC 3339 datetime string indicating when the User joined the Organization. - `string email` Email of the User. - `string name` Name of the User. - `BetaOrganizationRole role` Organization role of the User. #### Example ```php beta->organization->users->retrieve('user_id'); var_dump($betaOrganizationUser); ``` ##### Response (200) ```json { "id": "user_01WxYzAbCdEfGhJkMnPqRsTu", "added_at": "2024-10-30T23:58:27.427722Z", "email": "user@emaildomain.com", "name": "Jane Doe", "role": "admin", "type": "user" } ``` ### Update User `$client->beta->organization->users->update(string userID, Role role): OrganizationUser` **POST** `/v1/organizations/users/{user_id}` Update a member's organization role. #### Parameters - `userID: string` (path parameter) ID of the User. - `role: Role` 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 - `class OrganizationUser` - `"user" type` Object type. For Users, this is always `"user"`. - `string id` ID of the User. - `\Datetime addedAt` RFC 3339 datetime string indicating when the User joined the Organization. - `string email` Email of the User. - `string name` Name of the User. - `BetaOrganizationRole role` Organization role of the User. #### Example ```php beta->organization->users->update( 'user_id', role: 'user' ); var_dump($betaOrganizationUser); ``` ##### Response (200) ```json { "id": "user_01WxYzAbCdEfGhJkMnPqRsTu", "added_at": "2024-10-30T23:58:27.427722Z", "email": "user@emaildomain.com", "name": "Jane Doe", "role": "admin", "type": "user" } ``` ### Remove User `$client->beta->organization->users->remove(string userID): UserRemoveResponse` **DELETE** `/v1/organizations/users/{user_id}` Remove a member from the organization. #### Parameters - `userID: string` (path parameter) ID of the User. #### Returns - `class UserRemoveResponse` - `"user_deleted" type` Deleted object type. For Users, this is always `"user_deleted"`. - `string id` ID of the User. #### Example ```php beta->organization->users->remove('user_id'); var_dump($user); ``` ##### Response (200) ```json { "id": "user_01WxYzAbCdEfGhJkMnPqRsTu", "type": "user_deleted" } ``` ## Beta › Organization › Workspaces ### List Workspaces `$client->beta->organization->workspaces->list(?string afterID, ?string beforeID, ?bool includeArchived, ?bool includeDefault, ?int limit): Page` **GET** `/v1/organizations/workspaces` List Workspaces #### Parameters - `afterID?: 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. - `beforeID?: 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. - `includeArchived?: optional bool` (query parameter) Whether to include Workspaces that have been archived in the response default: false - `includeDefault?: optional bool` (query parameter) Whether to include the organization's default Workspace in the response default: false - `limit?: optional int` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. default: 20 #### Returns - `class Workspace` - `"workspace" type` Object type. For Workspaces, this is always `"workspace"`. - `string id` ID of the Workspace. - `?\Datetime archivedAt` RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived. - `string compartmentID` Identifier for this Workspace's encryption compartment. When you configure an AWS KMS customer-managed encryption key (CMEK) that isn't bound to a user profile, 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: your organization's own key is validated against this Workspace's own value when it is attached, so if its key policy uses the compartment condition, add this value to it before attaching the key. - `\Datetime createdAt` RFC 3339 datetime string indicating when the Workspace was created. - `DataResidency dataResidency` Data residency configuration. - `string displayColor` Hex color code representing the Workspace in the Anthropic Console. - `?string externalKeyID` 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 for an AWS KMS key is the key's ARN, and your organization's own 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. - `string name` Name of the Workspace. - `array tags` User-defined tags as string key-value pairs. Keys may not begin with `anthropic`. - `?string userProfileID` ID of the user profile attached to the Workspace, or null if it has none. Every inference request through a Workspace that has a user profile must name that profile. #### Example ```php beta->organization->workspaces->list( afterID: 'after_id', beforeID: 'before_id', includeArchived: true, includeDefault: true, limit: 1, ); var_dump($page); ``` ##### 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", "user_profile_id": "uprof_01SDCCSbTxrXDpWc1phhtcfK" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id" } ``` ### Create Workspace `$client->beta->organization->workspaces->create(string name, ?DataResidencyCreateConfig dataResidency, ?string displayColor, ?string externalKeyID, ?array tags, ?string userProfileID, ?list betas): Workspace` **POST** `/v1/organizations/workspaces` Create Workspace #### Parameters - `name: string` Name of the Workspace. - `dataResidency?: optional DataResidencyCreateConfig` Data residency configuration for the workspace. If omitted, defaults to `workspace_geo: "us"`, `allowed_inference_geos: "unrestricted"`, and `default_inference_geo: "global"`. - `displayColor?: optional string` Hex color code representing the Workspace in the Anthropic Console. - `externalKeyID?: 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 for an AWS KMS key is the key's ARN, and your organization's own 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 array` User-defined tags as string key-value pairs. Keys may not begin with `anthropic`. - `userProfileID?: optional string` ID of a user profile to attach to the Workspace. Every inference request through the Workspace must then name this user profile; the API rejects a request that names none or a different one. The user profile can't be replaced or removed later; only deleting the user profile clears it. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class Workspace` - `"workspace" type` Object type. For Workspaces, this is always `"workspace"`. - `string id` ID of the Workspace. - `?\Datetime archivedAt` RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived. - `string compartmentID` Identifier for this Workspace's encryption compartment. When you configure an AWS KMS customer-managed encryption key (CMEK) that isn't bound to a user profile, 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: your organization's own key is validated against this Workspace's own value when it is attached, so if its key policy uses the compartment condition, add this value to it before attaching the key. - `\Datetime createdAt` RFC 3339 datetime string indicating when the Workspace was created. - `DataResidency dataResidency` Data residency configuration. - `string displayColor` Hex color code representing the Workspace in the Anthropic Console. - `?string externalKeyID` 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 for an AWS KMS key is the key's ARN, and your organization's own 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. - `string name` Name of the Workspace. - `array tags` User-defined tags as string key-value pairs. Keys may not begin with `anthropic`. - `?string userProfileID` ID of the user profile attached to the Workspace, or null if it has none. Every inference request through a Workspace that has a user profile must name that profile. #### Example ```php beta->organization->workspaces->create( name: 'x', dataResidency: [ 'allowedInferenceGeos' => 'unrestricted', 'defaultInferenceGeo' => 'global', 'workspaceGeo' => 'us', ], displayColor: '#6C5BB9', externalKeyID: 'ekey_01SDCCSbTxrXDpWc1phhtcfK', tags: ['env' => 'prod', 'team' => 'platform'], userProfileID: 'uprof_01SDCCSbTxrXDpWc1phhtcfK', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaWorkspace); ``` ##### 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", "user_profile_id": "uprof_01SDCCSbTxrXDpWc1phhtcfK" } ``` ### Get Workspace `$client->beta->organization->workspaces->retrieve(string workspaceID): Workspace` **GET** `/v1/organizations/workspaces/{workspace_id}` Get Workspace #### Parameters - `workspaceID: string` (path parameter) ID of the Workspace. #### Returns - `class Workspace` - `"workspace" type` Object type. For Workspaces, this is always `"workspace"`. - `string id` ID of the Workspace. - `?\Datetime archivedAt` RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived. - `string compartmentID` Identifier for this Workspace's encryption compartment. When you configure an AWS KMS customer-managed encryption key (CMEK) that isn't bound to a user profile, 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: your organization's own key is validated against this Workspace's own value when it is attached, so if its key policy uses the compartment condition, add this value to it before attaching the key. - `\Datetime createdAt` RFC 3339 datetime string indicating when the Workspace was created. - `DataResidency dataResidency` Data residency configuration. - `string displayColor` Hex color code representing the Workspace in the Anthropic Console. - `?string externalKeyID` 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 for an AWS KMS key is the key's ARN, and your organization's own 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. - `string name` Name of the Workspace. - `array tags` User-defined tags as string key-value pairs. Keys may not begin with `anthropic`. - `?string userProfileID` ID of the user profile attached to the Workspace, or null if it has none. Every inference request through a Workspace that has a user profile must name that profile. #### Example ```php beta->organization->workspaces->retrieve( 'workspace_id' ); var_dump($betaWorkspace); ``` ##### 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", "user_profile_id": "uprof_01SDCCSbTxrXDpWc1phhtcfK" } ``` ### Update Workspace `$client->beta->organization->workspaces->update(string workspaceID, ?DataResidencyUpdateConfig dataResidency, ?string displayColor, ?string externalKeyID, ?string name, ?array tags, ?string userProfileID): Workspace` **POST** `/v1/organizations/workspaces/{workspace_id}` Update Workspace #### Parameters - `workspaceID: string` (path parameter) - `dataResidency?: optional DataResidencyUpdateConfig` Data residency configuration for the workspace. - `displayColor?: optional string` Hex color code representing the Workspace in the Anthropic Console. - `externalKeyID?: 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 for an AWS KMS key is the key's ARN, and your organization's own 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. - `tags?: optional array` User-defined tags as string key-value pairs. Keys may not begin with `anthropic`. - `userProfileID?: optional string` ID of a user profile to attach to the Workspace. Every inference request through the Workspace must then name this user profile; the API rejects a request that names none or a different one. Once set, it can't be replaced or removed (sending the same ID again changes nothing); only deleting the user profile clears it. The default Workspace can't have a user profile. #### Returns - `class Workspace` - `"workspace" type` Object type. For Workspaces, this is always `"workspace"`. - `string id` ID of the Workspace. - `?\Datetime archivedAt` RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived. - `string compartmentID` Identifier for this Workspace's encryption compartment. When you configure an AWS KMS customer-managed encryption key (CMEK) that isn't bound to a user profile, 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: your organization's own key is validated against this Workspace's own value when it is attached, so if its key policy uses the compartment condition, add this value to it before attaching the key. - `\Datetime createdAt` RFC 3339 datetime string indicating when the Workspace was created. - `DataResidency dataResidency` Data residency configuration. - `string displayColor` Hex color code representing the Workspace in the Anthropic Console. - `?string externalKeyID` 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 for an AWS KMS key is the key's ARN, and your organization's own 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. - `string name` Name of the Workspace. - `array tags` User-defined tags as string key-value pairs. Keys may not begin with `anthropic`. - `?string userProfileID` ID of the user profile attached to the Workspace, or null if it has none. Every inference request through a Workspace that has a user profile must name that profile. #### Example ```php beta->organization->workspaces->update( 'workspace_id', dataResidency: [ 'allowedInferenceGeos' => 'unrestricted', 'defaultInferenceGeo' => 'global' ], displayColor: '#6C5BB9', externalKeyID: 'ekey_01SDCCSbTxrXDpWc1phhtcfK', name: 'x', tags: ['env' => 'prod', 'team' => 'platform'], userProfileID: 'uprof_01SDCCSbTxrXDpWc1phhtcfK', ); var_dump($betaWorkspace); ``` ##### 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", "user_profile_id": "uprof_01SDCCSbTxrXDpWc1phhtcfK" } ``` ### Archive Workspace `$client->beta->organization->workspaces->archive(string workspaceID): Workspace` **POST** `/v1/organizations/workspaces/{workspace_id}/archive` Archive Workspace #### Parameters - `workspaceID: string` (path parameter) #### Returns - `class Workspace` - `"workspace" type` Object type. For Workspaces, this is always `"workspace"`. - `string id` ID of the Workspace. - `?\Datetime archivedAt` RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived. - `string compartmentID` Identifier for this Workspace's encryption compartment. When you configure an AWS KMS customer-managed encryption key (CMEK) that isn't bound to a user profile, 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: your organization's own key is validated against this Workspace's own value when it is attached, so if its key policy uses the compartment condition, add this value to it before attaching the key. - `\Datetime createdAt` RFC 3339 datetime string indicating when the Workspace was created. - `DataResidency dataResidency` Data residency configuration. - `string displayColor` Hex color code representing the Workspace in the Anthropic Console. - `?string externalKeyID` 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 for an AWS KMS key is the key's ARN, and your organization's own 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. - `string name` Name of the Workspace. - `array tags` User-defined tags as string key-value pairs. Keys may not begin with `anthropic`. - `?string userProfileID` ID of the user profile attached to the Workspace, or null if it has none. Every inference request through a Workspace that has a user profile must name that profile. #### Example ```php beta->organization->workspaces->archive( 'workspace_id' ); var_dump($betaWorkspace); ``` ##### 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", "user_profile_id": "uprof_01SDCCSbTxrXDpWc1phhtcfK" } ``` ## Beta › Organization › Workspaces › Rate Limits ### List Workspace Rate Limits `$client->beta->organization->workspaces->rateLimits->list(string workspaceID, ?GroupType groupType, ?bool includeInherited, ?int limit, ?string page): PageCursor` **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 - `workspaceID: string` (path parameter) The ID of the workspace. - `groupType?: optional GroupType` (query parameter) Filter by group type. - `includeInherited?: optional bool` (query parameter) Also list the limiter values the workspace inherits from the organization, including groups with no workspace-level override. default: false - `limit?: optional int` (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`. - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. #### Returns - `class BetaWorkspaceRateLimit` - `"workspace_rate_limit" type` Object type. Always `workspace_rate_limit` for workspace rate-limit entries. - `Group group` The rate-limit group this entry's limits apply to. - `list limits` 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`. - `?list models` Model names this entry's limits apply to, including aliases. `null` when `group.type` is not `"model_group"`. The list covers the models this workspace has access to, so it can differ between workspaces. - `string rateLimitID` The `id` of the organization's RateLimit entry this entry applies to. - `string workspaceID` ID of the Workspace this entry applies to. #### Example ```php beta->organization->workspaces->rateLimits->list( 'workspace_id', groupType: 'batch', includeInherited: true, limit: 1, page: 'page', ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "group": { "id": "id", "display_name": "display_name", "type": "model_group" }, "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" } ``` ### Set Workspace Rate Limits `$client->beta->organization->workspaces->rateLimits->update(string rateLimitID, string workspaceID, list limits): BetaWorkspaceRateLimit` **POST** `/v1/organizations/workspaces/{workspace_id}/rate_limits/{rate_limit_id}` Set or clear rate-limit overrides for one rate-limit group in a workspace. Only the limiter types named in `limits` change: an integer `value` sets that type's override and `null` clears it. Types not named keep their current value. A value above the organization's own limit is stored, but the organization limit still applies, so the lower of the two is enforced. Returns the targeted group's entry with this request applied, in the shape `GET /v1/organizations/workspaces/{workspace_id}/rate_limits` returns. Changes take effect within about an hour. #### Parameters - `workspaceID: string` (path parameter) The ID of the workspace. - `rateLimitID: string` (path parameter) The `id` of the organization's rate-limit entry to set overrides for. - `limits: list` Limits to set or clear. Unspecified limit types are unchanged. #### Returns - `class BetaWorkspaceRateLimit` - `"workspace_rate_limit" type` Object type. Always `workspace_rate_limit` for workspace rate-limit entries. - `Group group` The rate-limit group this entry's limits apply to. - `list limits` 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`. - `?list models` Model names this entry's limits apply to, including aliases. `null` when `group.type` is not `"model_group"`. The list covers the models this workspace has access to, so it can differ between workspaces. - `string rateLimitID` The `id` of the organization's RateLimit entry this entry applies to. - `string workspaceID` ID of the Workspace this entry applies to. #### Example ```php beta ->organization ->workspaces ->rateLimits ->update( 'rate_limit_id', workspaceID: 'workspace_id', limits: [['type' => BetaWorkspaceRateLimitType::FAST_ITPMCA, 'value' => 0]], ); var_dump($betaWorkspaceRateLimit); ``` ##### Response (200) ```json { "group": { "id": "id", "display_name": "display_name", "type": "model_group" }, "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" } ``` ## Beta › Organization › Workspaces › Members ### List Workspace Members `$client->beta->organization->workspaces->members->list(string workspaceID, ?string afterID, ?string beforeID, ?int limit): Page` **GET** `/v1/organizations/workspaces/{workspace_id}/members` List Workspace Members #### Parameters - `workspaceID: string` (path parameter) ID of the Workspace. - `afterID?: 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. - `beforeID?: 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 int` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. default: 20 #### Returns - `class WorkspaceMember` - `"workspace_member" type` Object type. For Workspace Members, this is always `"workspace_member"`. - `string userID` ID of the User. - `string workspaceID` ID of the Workspace. - `WorkspaceRole workspaceRole` Role of the Workspace Member. #### Example ```php beta->organization->workspaces->members->list( 'workspace_id', afterID: 'after_id', beforeID: 'before_id', limit: 1 ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "type": "workspace_member", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", "workspace_role": "workspace_admin" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id" } ``` ### Create Workspace Member `$client->beta->organization->workspaces->members->add(string workspaceID, string userID, NoBillingWorkspaceRole workspaceRole): WorkspaceMember` **POST** `/v1/organizations/workspaces/{workspace_id}/members` Create Workspace Member #### Parameters - `workspaceID: string` (path parameter) ID of the Workspace. - `userID: string` ID of the User. - `workspaceRole: NoBillingWorkspaceRole` Role of the new Workspace Member. Cannot be `workspace_billing`. #### Returns - `class WorkspaceMember` - `"workspace_member" type` Object type. For Workspace Members, this is always `"workspace_member"`. - `string userID` ID of the User. - `string workspaceID` ID of the Workspace. - `WorkspaceRole workspaceRole` Role of the Workspace Member. #### Example ```php beta->organization->workspaces->members->add( 'workspace_id', userID: 'user_01WxYzAbCdEfGhJkMnPqRsTu', workspaceRole: NoBillingWorkspaceRole::WORKSPACE_ADMIN, ); var_dump($betaWorkspaceMember); ``` ##### Response (200) ```json { "type": "workspace_member", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", "workspace_role": "workspace_admin" } ``` ### Get Workspace Member `$client->beta->organization->workspaces->members->retrieve(string userID, string workspaceID): WorkspaceMember` **GET** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}` Get Workspace Member #### Parameters - `workspaceID: string` (path parameter) ID of the Workspace. - `userID: string` (path parameter) ID of the User. #### Returns - `class WorkspaceMember` - `"workspace_member" type` Object type. For Workspace Members, this is always `"workspace_member"`. - `string userID` ID of the User. - `string workspaceID` ID of the Workspace. - `WorkspaceRole workspaceRole` Role of the Workspace Member. #### Example ```php beta ->organization ->workspaces ->members ->retrieve('user_id', workspaceID: 'workspace_id'); var_dump($betaWorkspaceMember); ``` ##### Response (200) ```json { "type": "workspace_member", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", "workspace_role": "workspace_admin" } ``` ### Update Workspace Member `$client->beta->organization->workspaces->members->update(string userID, string workspaceID, WorkspaceRole workspaceRole): WorkspaceMember` **POST** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}` Update Workspace Member #### Parameters - `workspaceID: string` (path parameter) ID of the Workspace. - `userID: string` (path parameter) ID of the User. - `workspaceRole: WorkspaceRole` New workspace role for the User. #### Returns - `class WorkspaceMember` - `"workspace_member" type` Object type. For Workspace Members, this is always `"workspace_member"`. - `string userID` ID of the User. - `string workspaceID` ID of the Workspace. - `WorkspaceRole workspaceRole` Role of the Workspace Member. #### Example ```php beta->organization->workspaces->members->update( 'user_id', workspaceID: 'workspace_id', workspaceRole: WorkspaceRole::WORKSPACE_ADMIN, ); var_dump($betaWorkspaceMember); ``` ##### Response (200) ```json { "type": "workspace_member", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", "workspace_role": "workspace_admin" } ``` ### Delete Workspace Member `$client->beta->organization->workspaces->members->remove(string userID, string workspaceID): MemberRemoveResponse` **DELETE** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}` Delete Workspace Member #### Parameters - `workspaceID: string` (path parameter) ID of the Workspace. - `userID: string` (path parameter) ID of the User. #### Returns - `class MemberRemoveResponse` - `"workspace_member_deleted" type` Deleted object type. For Workspace Members, this is always `"workspace_member_deleted"`. - `string userID` ID of the User. - `string workspaceID` ID of the Workspace. #### Example ```php beta->organization->workspaces->members->remove( 'user_id', workspaceID: 'workspace_id' ); var_dump($member); ``` ##### Response (200) ```json { "type": "workspace_member_deleted", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" } ``` ## Beta › Organization › Workspaces › Service Accounts ### List Service Account Workspace Members `$client->beta->organization->workspaces->serviceAccounts->list(string workspaceID, ?int limit, ?string page, ?list betas): PageCursor` **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=php). 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 - `workspaceID: string` (path parameter) ID of the workspace. - `limit?: optional int` (query parameter) Number of results per page. default: 20 - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class ServiceAccountWorkspaceMember` - `"service_account_workspace_member" type` - `?string createdByActorID` Tagged ID (`user_...`/`svac_...`) of the actor who created this membership. - `?bool implicit` 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. - `string serviceAccountID` Tagged service account ID (`svac_...`). - `string workspaceID` Tagged workspace ID (`wrkspc_...`). - `WorkspaceRole workspaceRole` Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role. #### Example ```php beta->organization->workspaces->serviceAccounts->list( 'workspace_id', limit: 1, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### 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 `$client->beta->organization->workspaces->serviceAccounts->add(string workspaceID, string serviceAccountID, NoBillingWorkspaceRole workspaceRole, ?list betas): ServiceAccountWorkspaceMember` **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=php). 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 - `workspaceID: string` (path parameter) ID of the workspace. - `serviceAccountID: string` Tagged service account ID to add. - `workspaceRole: NoBillingWorkspaceRole` Role to assign to the service account in this workspace. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class ServiceAccountWorkspaceMember` - `"service_account_workspace_member" type` - `?string createdByActorID` Tagged ID (`user_...`/`svac_...`) of the actor who created this membership. - `?bool implicit` 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. - `string serviceAccountID` Tagged service account ID (`svac_...`). - `string workspaceID` Tagged workspace ID (`wrkspc_...`). - `WorkspaceRole workspaceRole` Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role. #### Example ```php beta ->organization ->workspaces ->serviceAccounts ->add( 'workspace_id', serviceAccountID: 'service_account_id', workspaceRole: NoBillingWorkspaceRole::WORKSPACE_ADMIN, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaServiceAccountWorkspaceMember); ``` ##### 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 `$client->beta->organization->workspaces->serviceAccounts->retrieve(string serviceAccountID, string workspaceID, ?list betas): ServiceAccountWorkspaceMember` **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=php). 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 - `workspaceID: string` (path parameter) ID of the workspace. - `serviceAccountID: string` (path parameter) ID of the service account. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class ServiceAccountWorkspaceMember` - `"service_account_workspace_member" type` - `?string createdByActorID` Tagged ID (`user_...`/`svac_...`) of the actor who created this membership. - `?bool implicit` 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. - `string serviceAccountID` Tagged service account ID (`svac_...`). - `string workspaceID` Tagged workspace ID (`wrkspc_...`). - `WorkspaceRole workspaceRole` Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role. #### Example ```php beta ->organization ->workspaces ->serviceAccounts ->retrieve( 'service_account_id', workspaceID: 'workspace_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaServiceAccountWorkspaceMember); ``` ##### 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 `$client->beta->organization->workspaces->serviceAccounts->update(string serviceAccountID, string workspaceID, NoBillingWorkspaceRole workspaceRole, ?list betas): ServiceAccountWorkspaceMember` **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=php). 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 - `workspaceID: string` (path parameter) ID of the workspace. - `serviceAccountID: string` (path parameter) ID of the service account. - `workspaceRole: NoBillingWorkspaceRole` New role for the service account in this workspace. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class ServiceAccountWorkspaceMember` - `"service_account_workspace_member" type` - `?string createdByActorID` Tagged ID (`user_...`/`svac_...`) of the actor who created this membership. - `?bool implicit` 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. - `string serviceAccountID` Tagged service account ID (`svac_...`). - `string workspaceID` Tagged workspace ID (`wrkspc_...`). - `WorkspaceRole workspaceRole` Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role. #### Example ```php beta ->organization ->workspaces ->serviceAccounts ->update( 'service_account_id', workspaceID: 'workspace_id', workspaceRole: NoBillingWorkspaceRole::WORKSPACE_ADMIN, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaServiceAccountWorkspaceMember); ``` ##### 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 `$client->beta->organization->workspaces->serviceAccounts->remove(string serviceAccountID, string workspaceID, ?list betas): ServiceAccountRemoveResponse` **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=php). 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 - `workspaceID: string` (path parameter) ID of the workspace. - `serviceAccountID: string` (path parameter) ID of the service account. - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class ServiceAccountRemoveResponse` - `"service_account_workspace_member_deleted" type` - `string serviceAccountID` Tagged service account ID (`svac_...`) named in the delete request. Removal is idempotent; see the endpoint description for the implicit-membership no-op. - `string workspaceID` Tagged workspace ID (`wrkspc_...`) named in the delete request. #### Example ```php beta ->organization ->workspaces ->serviceAccounts ->remove( 'service_account_id', workspaceID: 'workspace_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($serviceAccount); ``` ##### 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 `$client->beta->organization->rateLimits->list(?GroupType groupType, ?int limit, ?string model, ?string page): PageCursor` **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 - `groupType?: optional GroupType` (query parameter) Filter by group type. - `limit?: optional int` (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`. - `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 - `class OrganizationRateLimit` - `"rate_limit" type` Object type. Always `rate_limit` for organization rate-limit entries. - `string id` Identifier of this rate-limit entry. It is stable within the organization and differs between organizations; the group's own identifier is `group.id`. Pass it as `rate_limit_id` to set a workspace's overrides for this group. - `Group group` The rate-limit group this entry's limits apply to. - `list limits` The limiter values that apply to this group. - `?list models` Model names this entry's limits apply to, including aliases. `null` when `group.type` is not `"model_group"`. The list covers the models your organization has access to, so it can differ between organizations. #### Example ```php beta->organization->rateLimits->list( groupType: 'batch', limit: 1, model: 'model', page: 'page' ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "id": "id", "group": { "id": "id", "display_name": "display_name", "type": "model_group" }, "limits": [ { "type": "type", "value": 0 } ], "models": [ "string" ], "type": "rate_limit" } ], "next_page": "next_page" } ``` ## Beta › Organization › Compliance Settings ### Get Compliance Settings `$client->beta->organization->complianceSettings->retrieve(): ComplianceSettings` **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 - `class ComplianceSettings` - `"compliance_settings" type` - `ComplianceSettingsState state` Whether the Compliance API is enabled for this organization. #### Example ```php beta ->organization ->complianceSettings ->retrieve(); var_dump($betaComplianceSettings); ``` ##### Response (200) ```json { "state": { "type": "enabled" }, "type": "compliance_settings" } ``` ### Update Compliance Settings `$client->beta->organization->complianceSettings->update(ComplianceSettingsStateParam state): ComplianceSettings` **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. Access Transparency events are an exception: they are still captured while the Compliance API is disabled, and the Compliance API activity feed returns them once it is enabled again. `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: ComplianceSettingsStateParam` Desired state. Accepts the string shorthand "enabled" or "disabled" in place of the object form; the response always returns the canonical object form. #### Returns - `class ComplianceSettings` - `"compliance_settings" type` - `ComplianceSettingsState state` Whether the Compliance API is enabled for this organization. #### Example ```php beta ->organization ->complianceSettings ->update(state: ['type' => 'enabled']); var_dump($betaComplianceSettings); ``` ##### Response (200) ```json { "state": { "type": "enabled" }, "type": "compliance_settings" } ``` ## Beta › Organization › Analytics › Summaries ### Get Activity Summaries `$client->beta->organization->analytics->summaries->list(\Datetime startingDate, ?\Datetime endingDate, ?list filter, ?int limit, ?string page): PageCursor` **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 - `startingDate: \Datetime` (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. - `endingDate?: optional \Datetime` (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. - `filter?: optional list` (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. - `limit?: optional int` (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. - `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 - `class AnalyticsSingleDayActivitySummary` - `?int assignedSeatCount` 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. - `int coworkDailyActiveUserCount` Number of users with Cowork activity on the requested day - `int coworkMonthlyActiveUserCount` Number of users with Cowork activity in the 30-day rolling window - `int coworkWeeklyActiveUserCount` Number of users with Cowork activity in the 7-day rolling window - `int dailyActiveUserCount` Number of users with token consumption on the requested day - `?float dailyAdoptionRate` 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. - `\Datetime endingAt` End of the aggregation period (exclusive), UTC midnight in RFC 3339 format (e.g. `2026-01-16T00:00:00Z`). - `int monthlyActiveUserCount` Number of users with token consumption in the 30-day rolling window - `?float monthlyAdoptionRate` 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. - `?int pendingInviteCount` Number of pending invitations to join the organization. Null when the response is scoped to an RBAC group. - `\Datetime startingAt` Start of the aggregation period (inclusive), UTC midnight in RFC 3339 format (e.g. `2026-01-15T00:00:00Z`). - `int weeklyActiveUserCount` Number of users with token consumption in the 7-day rolling window - `?float weeklyAdoptionRate` 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. - `?int chatCoworkUnifiedDailyActiveUserCount` Number of users with activity in Chat and Cowork unified on the requested day. Omitted from the response where Chat and Cowork unified is not available. - `?int chatCoworkUnifiedMonthlyActiveUserCount` 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 where Chat and Cowork unified is not available. - `?int chatCoworkUnifiedWeeklyActiveUserCount` Number of users with activity in Chat and Cowork unified in the 7-day rolling window. Omitted from the response where Chat and Cowork unified is not available. - `?int chatDailyActiveUserCount` 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. - `?int chatMonthlyActiveUserCount` 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. - `?int chatWeeklyActiveUserCount` 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. - `?int claudeCodeDailyActiveUserCount` 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. - `?int claudeCodeMonthlyActiveUserCount` 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. - `?int claudeCodeWeeklyActiveUserCount` 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. - `?int claudeDesignDailyActiveUserCount` 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. - `?int claudeDesignMonthlyActiveUserCount` 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. - `?int claudeDesignWeeklyActiveUserCount` 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. - `?int officeAgentDailyActiveUserCount` 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. - `?int officeAgentMonthlyActiveUserCount` 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. - `?int officeAgentWeeklyActiveUserCount` 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. - `?int scienceDailyActiveUserCount` 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. - `?int scienceEntitledUserCount` 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. - `?int scienceMonthlyActiveUserCount` 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. - `?int scienceWeeklyActiveUserCount` 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. #### Example ```php beta->organization->analytics->summaries->list( startingDate: '2019-12-27', endingDate: '2019-12-27', filter: ['string'], limit: 1, page: 'page', ); var_dump($page); ``` ##### 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" } ``` ## Beta › Organization › Analytics › Users ### List User Activity `$client->beta->organization->analytics->users->list(?\Datetime date, ?\Datetime endingDate, ?list filter, ?list groupBy, ?int limit, ?AnalyticsOrder order, ?string orderBy, ?string page, ?\Datetime startingDate): PageCursor` **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 \Datetime` (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. - `endingDate?: optional \Datetime` (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`. - `filter?: optional list` (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`. - `groupBy?: optional list` (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. - `limit?: optional int` (query parameter) Number of results per page (1-1000, default 100). - `order?: optional AnalyticsOrder` (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. - `orderBy?: 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. - `startingDate?: optional \Datetime` (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. #### Returns - `class AnalyticsUserActivity` - `AnalyticsChatMetrics chatMetrics` Claude.ai activity metrics for a single user on a given day. - `AnalyticsClaudeCodeMetrics claudeCodeMetrics` Claude Code activity metrics for a single user on a given day. - `AnalyticsCoworkMetrics coworkMetrics` Cowork activity metrics for a single user on a given day. - `AnalyticsDesignMetrics designMetrics` Claude Design activity metrics for a single user on a given day. - `?int distinctUserCount` 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. - `AnalyticsOfficeMetrics officeMetrics` Office Agent activity metrics for a single user on a given day, broken out by Office product. - `AnalyticsScienceMetrics scienceMetrics` Claude Science activity metrics for a single user on a given day. - `?AnalyticsUser user` The user this row describes. Null on rows aggregated across users. - `int webSearchCount` Number of web searches performed - `?AnalyticsChatCoworkUnifiedMetrics chatCoworkUnifiedMetrics` 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 where Chat and Cowork unified is not available. - `?\Datetime lastActivityDate` 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. - `?string rbacGroupID` Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`. - `?string rbacGroupName` 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. #### Example ```php beta->organization->analytics->users->list( date: '2019-12-27', endingDate: '2019-12-27', filter: ['string'], groupBy: [AnalyticsUserGroupBy::RBAC_GROUP_ID], limit: 1, order: AnalyticsOrder::ASC, orderBy: 'order_by', page: 'page', startingDate: '2019-12-27', ); var_dump($page); ``` ##### 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_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 }, "design_metrics": { "distinct_projects_created_count": 0, "distinct_projects_used_count": 0, "distinct_session_count": 0, "message_count": 0 }, "distinct_user_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 }, "user": { "id": "id", "email_address": "email_address", "type": "user" }, "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 } }, "last_activity_date": "2019-12-27", "rbac_group_id": "rbac_group_id", "rbac_group_name": "rbac_group_name" } ], "next_page": "next_page" } ``` ## Beta › Organization › Analytics › Apps › Chat › Projects ### Get Chat Project Usage `$client->beta->organization->analytics->apps->chat->projects->list(?\Datetime date, ?\Datetime endingDate, ?list filter, ?list groupBy, ?int limit, ?AnalyticsOrder order, ?string orderBy, ?string page, ?\Datetime startingDate): PageCursor` **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 \Datetime` (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. - `endingDate?: optional \Datetime` (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`. - `filter?: optional list` (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. - `groupBy?: optional list` (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. - `limit?: optional int` (query parameter) Number of results per page (1-1000, default 100). - `order?: optional AnalyticsOrder` (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. - `orderBy?: 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. - `startingDate?: optional \Datetime` (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. #### Returns - `class AnalyticsProjectActivity` - `?\Datetime createdAt` Project creation timestamp in RFC 3339 format. Null if the project was deleted before attribution was recorded. - `?AnalyticsUser createdBy` User who created the project. Null if the project was deleted before attribution was recorded, or if the creator's account no longer exists. - `?int distinctConversationCount` Number of distinct conversations in the project. Null on aggregated rows where a distinct count cannot be computed. - `int distinctUserCount` 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. - `int messageCount` Number of messages sent in the project on the requested day - `string projectID` Tagged project identifier (e.g. `claude_proj_...`) - `string projectName` Name of the project - `?string rbacGroupID` Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`. - `?string rbacGroupName` 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. - `?string userID` Tagged user identifier (e.g. `user_...`). Present only when the request grouped by `user_id`. #### Example ```php beta->organization->analytics->apps->chat->projects->list( date: '2019-12-27', endingDate: '2019-12-27', filter: ['string'], groupBy: [AnalyticsProjectGroupBy::RBAC_GROUP_ID], limit: 1, order: AnalyticsOrder::ASC, orderBy: 'order_by', page: 'page', startingDate: '2019-12-27', ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "created_at": "2019-12-27T18:11:19.117Z", "created_by": { "id": "id", "email_address": "email_address", "type": "user" }, "distinct_conversation_count": 0, "distinct_user_count": 0, "message_count": 0, "project_id": "project_id", "project_name": "project_name", "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 `$client->beta->organization->analytics->connectors->list(?\Datetime date, ?\Datetime endingDate, ?list filter, ?list groupBy, ?int limit, ?AnalyticsOrder order, ?string orderBy, ?string page, ?\Datetime startingDate): PageCursor` **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 \Datetime` (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. - `endingDate?: optional \Datetime` (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`. - `filter?: optional list` (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 where Chat and Cowork unified is available. - `groupBy?: optional list` (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. - `limit?: optional int` (query parameter) Number of results per page (1-1000, default 100). - `order?: optional AnalyticsOrder` (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. - `orderBy?: 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. - `startingDate?: optional \Datetime` (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. #### Returns - `class AnalyticsConnectorActivity` - `AnalyticsConnectorChatMetrics chatMetrics` Claude.ai activity metrics for a single connector on a given day. - `AnalyticsConnectorClaudeCodeMetrics claudeCodeMetrics` Claude Code activity metrics for a single connector on a given day. - `?string connectorDisplayName` 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. - `string connectorName` 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. - `AnalyticsConnectorCoworkMetrics coworkMetrics` Cowork activity metrics for a single connector on a given day. - `int distinctUserCount` 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. - `?int individualAuthDistinctUserCount` 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. - `?int managedAuthDistinctUserCount` 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. - `AnalyticsConnectorOfficeMetrics officeMetrics` Office Agent activity metrics for a single connector on a given day, broken out by Office product. - `?int readCallCount` 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. - `?int unclassifiedCallCount` 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. - `?int writeCallCount` 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. - `?AnalyticsConnectorChatCoworkUnifiedMetrics chatCoworkUnifiedMetrics` 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 where Chat and Cowork unified is not available. - `?string product` 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`. - `?string rbacGroupID` Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`. - `?string rbacGroupName` 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. - `?string userID` Tagged user identifier (e.g. `user_...`). Present only when the request grouped by `user_id`. #### Example ```php beta->organization->analytics->connectors->list( date: '2019-12-27', endingDate: '2019-12-27', filter: ['string'], groupBy: [AnalyticsConnectorGroupBy::PRODUCT], limit: 1, order: AnalyticsOrder::ASC, orderBy: 'order_by', page: 'page', startingDate: '2019-12-27', ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "chat_metrics": { "distinct_conversation_connector_used_count": 0 }, "claude_code_metrics": { "distinct_session_connector_used_count": 0 }, "connector_display_name": "connector_display_name", "connector_name": "connector_name", "cowork_metrics": { "distinct_session_connector_used_count": 0 }, "distinct_user_count": 0, "individual_auth_distinct_user_count": 0, "managed_auth_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 } }, "read_call_count": 0, "unclassified_call_count": 0, "write_call_count": 0, "chat_cowork_unified_metrics": { "chat": { "distinct_conversation_connector_used_count": 0 }, "sessions": { "distinct_session_connector_used_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 › Plugins ### Get Plugin Usage `$client->beta->organization->analytics->plugins->list(?\Datetime date, ?\Datetime endingDate, ?list filter, ?list groupBy, ?int limit, ?AnalyticsOrder order, ?string orderBy, ?string page, ?\Datetime startingDate): PageCursor` **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 \Datetime` (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. - `endingDate?: optional \Datetime` (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`. - `filter?: optional list` (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 where Chat and Cowork unified is available. - `groupBy?: optional list` (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. - `limit?: optional int` (query parameter) Number of results per page (1-1000, default 100). - `order?: optional AnalyticsOrder` (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. - `orderBy?: 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. - `startingDate?: optional \Datetime` (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. #### Returns - `class AnalyticsPluginActivity` - `AnalyticsPluginClaudeCodeMetrics claudeCodeMetrics` Claude Code activity metrics for a single plugin on a given day. - `AnalyticsPluginCoworkMetrics coworkMetrics` Cowork activity metrics for a single plugin on a given day. - `int distinctUserCount` 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. - `?int installCount` 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. - `int invocationCount` Number of plugin invocations on the requested day - `?string pluginID` 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. - `string pluginName` Name of the plugin - `?AnalyticsPluginChatCoworkUnifiedMetrics chatCoworkUnifiedMetrics` 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 where Chat and Cowork unified is not available. - `?string product` 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`. - `?string rbacGroupID` Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`. - `?string rbacGroupName` 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. - `?string userID` Tagged user identifier (e.g. `user_...`). Present only when the request grouped by `user_id`. #### Example ```php beta->organization->analytics->plugins->list( date: '2019-12-27', endingDate: '2019-12-27', filter: ['string'], groupBy: [AnalyticsPluginGroupBy::PRODUCT], limit: 1, order: AnalyticsOrder::ASC, orderBy: 'order_by', page: 'page', startingDate: '2019-12-27', ); var_dump($page); ``` ##### 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_id": "plugin_id", "plugin_name": "plugin_name", "chat_cowork_unified_metrics": { "distinct_session_plugin_used_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 › Skills ### Get Skill Usage `$client->beta->organization->analytics->skills->list(?\Datetime date, ?\Datetime endingDate, ?list filter, ?list groupBy, ?int limit, ?AnalyticsOrder order, ?string orderBy, ?string page, ?\Datetime startingDate): PageCursor` **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 \Datetime` (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. - `endingDate?: optional \Datetime` (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`. - `filter?: optional list` (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 where Chat and Cowork unified is available. - `groupBy?: optional list` (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. - `limit?: optional int` (query parameter) Number of results per page (1-1000, default 100). - `order?: optional AnalyticsOrder` (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. - `orderBy?: 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. - `startingDate?: optional \Datetime` (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. #### Returns - `class AnalyticsSkillActivity` - `?string attributedListPrice` 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. - `AnalyticsSkillChatMetrics chatMetrics` Claude.ai activity metrics for a single skill on a given day. - `AnalyticsSkillClaudeCodeMetrics claudeCodeMetrics` Claude Code activity metrics for a single skill on a given day. - `AnalyticsSkillCoworkMetrics coworkMetrics` Cowork activity metrics for a single skill on a given day. - `?string currency` 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. - `int distinctUserCount` 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. - `?int enableCount` 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`). - `?string estimatedOverageSpend` 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. - `?int invocationCount` 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. - `AnalyticsSkillOfficeMetrics officeMetrics` Office Agent activity metrics for a single skill on a given day, broken out by Office product. - `?ShareStatus shareStatus` 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}`. - `?string skillDisplayName` 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. - `string skillName` Name of the skill - `?AnalyticsSkillChatCoworkUnifiedMetrics chatCoworkUnifiedMetrics` 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 where Chat and Cowork unified is not available. - `?string product` 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`. - `?string rbacGroupID` Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`. - `?string rbacGroupName` 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. - `?string userID` Tagged user identifier (e.g. `user_...`). Present only when the request grouped by `user_id`. #### Example ```php beta->organization->analytics->skills->list( date: '2019-12-27', endingDate: '2019-12-27', filter: ['string'], groupBy: [AnalyticsSkillGroupBy::PRODUCT], limit: 1, order: AnalyticsOrder::ASC, orderBy: 'order_by', page: 'page', startingDate: '2019-12-27', ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "attributed_list_price": "attributed_list_price", "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 }, "currency": "currency", "distinct_user_count": 0, "enable_count": 0, "estimated_overage_spend": "estimated_overage_spend", "invocation_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 } }, "share_status": "organization", "skill_display_name": "skill_display_name", "skill_name": "skill_name", "chat_cowork_unified_metrics": { "chat": { "distinct_conversation_skill_used_count": 0 }, "sessions": { "distinct_session_skill_used_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 › Artifacts ### Get Artifact Activity `$client->beta->organization->analytics->artifacts->list(\Datetime date, ?list filter, ?list groupBy, ?int limit, ?string page): PageCursor` **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: \Datetime` (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. - `filter?: optional list` (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 where Chat and Cowork unified is available. - `groupBy?: optional list` (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. - `limit?: optional int` (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. - `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 - `class AnalyticsArtifactActivity` - `string artifactType` 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`. - `int artifactsCreatedCount` Number of artifacts created in this bucket on the requested day - `int distinctUserCount` Number of distinct users who created artifacts in this bucket on the requested day - `bool isShared` 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). - `int publishedArtifactsCreatedCount` Number of those artifacts that have been published (for Claude Code / Cowork artifacts: open to anyone with the link); never exceeds `artifacts_created_count` - `?string product` 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`. - `?string rbacGroupID` Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`. - `?string rbacGroupName` 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. - `?string userID` Tagged user identifier (e.g. `user_...`). Present only when the request grouped by `user_id`. #### Example ```php beta->organization->analytics->artifacts->list( date: '2019-12-27', filter: ['string'], groupBy: [AnalyticsArtifactGroupBy::PRODUCT], limit: 1, page: 'page', ); var_dump($page); ``` ##### 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 ### Get Token Usage By Dimension `$client->beta->organization->analytics->usage->list(\Datetime startingAt, ?list actorIDs, ?list actorTypes, ?list agentIDs, ?list apiKeyIDs, ?list claudeTagCategories, ?list claudeTagUserIDs, ?list contextWindows, ?list deploymentIDs, ?\Datetime endingAt, ?list environmentIDs, ?bool excludeDeletedUsers, ?list groupBy, ?list inferenceGeos, ?int limit, ?list models, ?AnalyticsUsageCostSortOrder order, ?BetaAnalyticsUsageOrderBy orderBy, ?string page, ?list products, ?list rbacGroupIDs, ?list serviceTiers, ?list sessionIDs, ?list slackChannelIDs, ?list speeds, ?AnalyticsTimeBucketWidth timeBucketWidth, ?list userProfileIDs, ?list workspaceIDs, ?list betas): ReportPageCursor` **GET** `/v1/organizations/analytics/usage` Get token usage across a date range, broken out by dimension. Returns one row per combination of the requested `group_by[]` dimensions (and time bucket, when `time_bucket_width` is set) that has usage in the range, ranked by the `order_by` metric or ordered by time bucket; every combination is returned across pages. With no `group_by[]` and no `time_bucket_width`, a single row aggregates the whole range. Includes all usage, whether or not it is attributable to a seat user. Requires an API key with the `read:analytics` scope, or an Admin API key. #### Parameters - `startingAt: \Datetime` (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. - `actorIDs?: optional list` (query parameter) Filter to usage attributed to specific identities, by tagged ID: a `user_...`, `svac_...` (service account), or `apikey_...` ID. An `apikey_` entry matches only usage attributed to the key itself, not usage on that key attributed to a user or service account (use `api_key_ids[]` for every request a key authenticated). Federated identities have no tagged ID; select them with `actor_types[]`. Use `group_by[]=actor` to break out per-identity values. - `actorTypes?: optional list` (query parameter) Filter to usage attributed to specific kinds of identity. Use `group_by[]=actor_type` to break out per-kind values. - `agentIDs?: optional list` (query parameter) Filter to usage incurred by sessions of specific Claude Managed Agents agents. Use `group_by[]=agent_id` to break out per-agent values. Claude Developer Platform organizations only. - `apiKeyIDs?: optional list` (query parameter) Filter to usage authenticated by specific API keys, by tagged API key ID (`apikey_...`), whichever identity the usage is attributed to. Include an empty entry (`api_key_ids[]=`) to also match usage that no API key authenticated. Use `group_by[]=api_key_id` to break out per-key values; usage without a key has a null `api_key_id`. Claude Developer Platform organizations only. - `claudeTagCategories?: optional list` (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. - `claudeTagUserIDs?: optional list` (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. - `contextWindows?: optional list` (query parameter) Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values. - `deploymentIDs?: optional list` (query parameter) Filter to usage incurred by Claude Managed Agents sessions that specific deployments started. Use `group_by[]=deployment_id` to break out per-deployment values. Claude Developer Platform organizations only. - `endingAt?: optional \Datetime` (query parameter) End of range, exclusive. Required when `time_bucket_width` is set. Without `time_bucket_width`, defaults to the earlier of now and `starting_at` + 31 days. The range may span at most 31 days. - `environmentIDs?: optional list` (query parameter) Filter to usage incurred by Claude Managed Agents sessions that ran in specific environments. Use `group_by[]=environment_id` to break out per-environment values. Claude Developer Platform organizations only. - `excludeDeletedUsers?: optional bool` (query parameter) If true, omit rows whose `actor` is a `user_actor` with `deleted: true`. Requires `group_by[]=actor`. Rows for other actor types, and rows whose `actor` is null, are always kept. A page may contain fewer than `limit` rows; use `has_more` and `next_page` to paginate as usual. default: false - `groupBy?: optional list` (query parameter) Dimensions to break usage out by (at most 5): one row per combination of their values with usage in the range (and per time bucket, when `time_bucket_width` is set), every combination returned across pages rather than a capped top set. When omitted, a single row aggregates the whole range. - `inferenceGeos?: optional list` (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. - `limit?: optional int` (query parameter) Number of rows per page (1-1000, default 20). `cost_type`/`token_type` fan-out rows (cost endpoint only) do not count toward this limit, so `data` can exceed it. default: 20 - `models?: optional list` (query parameter) Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values. - `order?: optional AnalyticsUsageCostSortOrder` (query parameter) Sort direction of the `order_by` metric, or of the time buckets when `order_by` is `time` and `time_bucket_width` is set. Defaults to `desc`. - `orderBy?: optional BetaAnalyticsUsageOrderBy` (query parameter) Row order. A metric ranks rows by that metric in the `order` direction. `time` orders rows by time bucket in the `order` direction (newest first by default) and, within a bucket, by `total_tokens`, highest first. `time` takes effect only with `time_bucket_width`; without it, `time` is the same as `total_tokens`. Defaults to `total_tokens`. - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `products?: optional list` (query parameter) Product surfaces to include. Defaults to all products. - `rbacGroupIDs?: optional list` (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. - `serviceTiers?: optional list` (query parameter) Filter to specific service tiers. Use `group_by[]=service_tier` to break out per-tier values. Claude Developer Platform organizations only; matches nothing for a Claude Enterprise organization. - `sessionIDs?: optional list` (query parameter) Filter to usage incurred by specific Claude Managed Agents sessions, by tagged session ID (`sesn_...`). Use `group_by[]=session_id` to break out per-session values. Claude Developer Platform organizations only. - `slackChannelIDs?: optional list` (query parameter) Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values. - `speeds?: optional list` (query parameter) Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values. - `timeBucketWidth?: optional AnalyticsTimeBucketWidth` (query parameter) Time-bucket granularity. When set, rows are returned per time bucket (one per bucket and dimension combination with usage) and each row's `starting_at` and `ending_at` are that bucket's bounds; the time bucket counts toward `limit`. `ending_at` is required when `time_bucket_width` is set, and with `time_bucket_width="1m"` the range may span at most 24 hours. When omitted, each row aggregates the requested range with `starting_at` and `ending_at` each rounded down to the hour. - `userProfileIDs?: optional list` (query parameter) Filter to usage attributed to specific user profiles, by tagged user profile ID (`uprof_...`). Use `group_by[]=user_profile_id` to break out per-profile values. Claude Developer Platform organizations only. - `workspaceIDs?: optional list` (query parameter) Filter to usage in specific workspaces, by tagged workspace ID (`wrkspc_...`). Use `group_by[]=workspace_id` to break out per-workspace values. Claude Developer Platform organizations only; matches nothing for a Claude Enterprise organization. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `analytics-usage-cost-2026-08-24` in this header. #### Returns - `class BetaAnalyticsUsageItem` - `\Datetime endingAt` End of the period this row covers (exclusive), as an RFC 3339 UTC timestamp: the end of the row's time bucket when a time-bucket width is set; otherwise the requested `ending_at` (or, when omitted, the earlier of now and `starting_at` plus 31 days) rounded down to the hour, because without a time bucket the report covers whole hours. - `BetaAnalyticsUsageGroup group` The dimension values this row's usage is broken out by. - `\Datetime startingAt` Start of the period this row covers (inclusive), as an RFC 3339 UTC timestamp: the start of the row's time bucket when a time-bucket width is set, otherwise the requested `starting_at` rounded down to the hour. - `BetaAnalyticsUsageMetrics usage` Token usage for this row. #### Example ```php beta->organization->analytics->usage->list( startingAt: new \DateTimeImmutable('2026-09-01T00:00:00Z'), actorIDs: ['user_01WxYzAbCdEfGhJkMnPqRsTu'], actorTypes: [AnalyticsActorType::SERVICE_ACCOUNT_ACTOR], agentIDs: ['agent_01VHd3EAGJ6PLkP9LM7DDu3f'], apiKeyIDs: ['apikey_01Rj2N8SVvo6BePZj99NhmiT'], claudeTagCategories: [AnalyticsClaudeTagCategory::ENGAGED], claudeTagUserIDs: ['U0123ABCDEF'], contextWindows: [AnalyticsContextWindow::FROM_0_TO_200K], deploymentIDs: ['depl_01JFC6ihzZHtAuyHsaENdJhY'], endingAt: new \DateTimeImmutable('2026-10-01T00:00:00Z'), environmentIDs: ['env_017oTjuGedHtjhJauVC5xGJD'], excludeDeletedUsers: true, groupBy: [BetaAnalyticsUsageGroupBy::ACTOR], inferenceGeos: [AnalyticsInferenceGeoFilter::GLOBAL], limit: 1, models: ['string'], order: AnalyticsUsageCostSortOrder::ASC, orderBy: BetaAnalyticsUsageOrderBy::OUTPUT_TOKENS, page: 'page', products: [AnalyticsUsageCostProductFilter::CHAT], rbacGroupIDs: ['rbac_group_012rppKaSVsmTo6NqRDXQXNF'], serviceTiers: [AnalyticsServiceTier::BATCH], sessionIDs: ['sesn_0187kPDyNCwibNNvfaPEApCJ'], slackChannelIDs: ['C0123ABCDEF'], speeds: [AnalyticsSpeed::FAST], timeBucketWidth: AnalyticsTimeBucketWidth::DAY, userProfileIDs: ['uprof_01M33NeYUQK2WV9PpYcsPHLi'], workspaceIDs: ['wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ'], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "ending_at": "2026-10-01T00:00:00Z", "group": { "actor": { "deleted": false, "email_address": "user@emaildomain.com", "name": "Jane Doe", "type": "user_actor", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "actor_type": "user_actor", "agent_id": "agent_01VHd3EAGJ6PLkP9LM7DDu3f", "api_key_id": "apikey_01Rj2N8SVvo6BePZj99NhmiT", "claude_tag_category": "dm", "claude_tag_user_id": "U0123ABCDEF", "context_window": "0-200k", "deployment_id": "depl_01JFC6ihzZHtAuyHsaENdJhY", "environment_id": "env_017oTjuGedHtjhJauVC5xGJD", "inference_geo": "global", "model": "claude-opus-5-5", "product": "chat", "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "service_tier": "standard", "session_id": "sesn_0187kPDyNCwibNNvfaPEApCJ", "slack_channel_id": "C0123ABCDEF", "speed": "fast", "user_profile_id": "uprof_01M33NeYUQK2WV9PpYcsPHLi", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" }, "starting_at": "2026-09-01T00:00:00Z", "usage": { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 3200000, "output_tokens": 891000, "requests": 128, "server_tool_use": { "web_search_requests": 10 }, "total_tokens": 5375500, "uncached_input_tokens": 1284500 } } ], "data_refreshed_at": "2026-10-01T04:02:11Z", "has_more": true, "next_page": "next_page" } ``` ## Beta › Organization › Analytics › Cost ### Get Cost By Dimension `$client->beta->organization->analytics->cost->list(\Datetime startingAt, ?list actorIDs, ?list actorTypes, ?list agentIDs, ?list apiKeyIDs, ?list claudeTagCategories, ?list claudeTagUserIDs, ?list contextWindows, ?list deploymentIDs, ?\Datetime endingAt, ?list environmentIDs, ?bool excludeDeletedUsers, ?list groupBy, ?list inferenceGeos, ?int limit, ?list models, ?AnalyticsUsageCostSortOrder order, ?BetaAnalyticsCostOrderBy orderBy, ?string page, ?list products, ?list rbacGroupIDs, ?list serviceTiers, ?list sessionIDs, ?list slackChannelIDs, ?list speeds, ?AnalyticsTimeBucketWidth timeBucketWidth, ?list userProfileIDs, ?list workspaceIDs, ?list betas): ReportPageCursor` **GET** `/v1/organizations/analytics/cost` Get cost in USD across a date range, broken out by dimension. Returns one row per combination of the requested `group_by[]` dimensions (and time bucket, when `time_bucket_width` is set) that has cost in the range, ranked by spend or ordered by time bucket; every combination is returned across pages. With no `group_by[]` and no `time_bucket_width`, a single row aggregates the whole range. Includes all cost, whether or not it is attributable to a seat user. Requires an API key with the `read:analytics` scope, or an Admin API key. #### Parameters - `startingAt: \Datetime` (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. - `actorIDs?: optional list` (query parameter) Filter to usage attributed to specific identities, by tagged ID: a `user_...`, `svac_...` (service account), or `apikey_...` ID. An `apikey_` entry matches only usage attributed to the key itself, not usage on that key attributed to a user or service account (use `api_key_ids[]` for every request a key authenticated). Federated identities have no tagged ID; select them with `actor_types[]`. Use `group_by[]=actor` to break out per-identity values. - `actorTypes?: optional list` (query parameter) Filter to usage attributed to specific kinds of identity. Use `group_by[]=actor_type` to break out per-kind values. - `agentIDs?: optional list` (query parameter) Filter to usage incurred by sessions of specific Claude Managed Agents agents. Use `group_by[]=agent_id` to break out per-agent values. Claude Developer Platform organizations only. - `apiKeyIDs?: optional list` (query parameter) Filter to usage authenticated by specific API keys, by tagged API key ID (`apikey_...`), whichever identity the usage is attributed to. Include an empty entry (`api_key_ids[]=`) to also match usage that no API key authenticated. Use `group_by[]=api_key_id` to break out per-key values; usage without a key has a null `api_key_id`. Claude Developer Platform organizations only. - `claudeTagCategories?: optional list` (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. - `claudeTagUserIDs?: optional list` (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. - `contextWindows?: optional list` (query parameter) Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values. - `deploymentIDs?: optional list` (query parameter) Filter to usage incurred by Claude Managed Agents sessions that specific deployments started. Use `group_by[]=deployment_id` to break out per-deployment values. Claude Developer Platform organizations only. - `endingAt?: optional \Datetime` (query parameter) End of range, exclusive. Required when `time_bucket_width` is set. Without `time_bucket_width`, defaults to the earlier of now and `starting_at` + 31 days. The range may span at most 31 days. - `environmentIDs?: optional list` (query parameter) Filter to usage incurred by Claude Managed Agents sessions that ran in specific environments. Use `group_by[]=environment_id` to break out per-environment values. Claude Developer Platform organizations only. - `excludeDeletedUsers?: optional bool` (query parameter) If true, omit rows whose `actor` is a `user_actor` with `deleted: true`. Requires `group_by[]=actor`. Rows for other actor types, and rows whose `actor` is null, are always kept. A page may contain fewer than `limit` rows; use `has_more` and `next_page` to paginate as usual. default: false - `groupBy?: optional list` (query parameter) Dimensions to break cost out by (at most 5, not counting `cost_type` and `token_type`): one row per combination of their values with cost in the range (and per time bucket, when `time_bucket_width` is set), every combination returned across pages rather than a capped top set. `cost_type` and `token_type` do not count toward `limit`: `cost_type` returns one row per cost component (tokens, web search, code execution, and `session_usage`, Claude Managed Agents session time); `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, code-execution and session-usage rows. When omitted, a single row aggregates the whole range. - `inferenceGeos?: optional list` (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. - `limit?: optional int` (query parameter) Number of rows per page (1-1000, default 20). `cost_type`/`token_type` fan-out rows (cost endpoint only) do not count toward this limit, so `data` can exceed it. default: 20 - `models?: optional list` (query parameter) Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values. - `order?: optional AnalyticsUsageCostSortOrder` (query parameter) Sort direction of the `order_by` metric, or of the time buckets when `order_by` is `time` and `time_bucket_width` is set. Defaults to `desc`. - `orderBy?: optional BetaAnalyticsCostOrderBy` (query parameter) Row order. A metric ranks rows by that metric in the `order` direction. `time` orders rows by time bucket in the `order` direction (newest first by default) and, within a bucket, by `amount`, highest first. `time` takes effect only with `time_bucket_width`; without it, `time` is the same as `amount`. Defaults to `amount`. - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `products?: optional list` (query parameter) Product surfaces to include. Defaults to all products. - `rbacGroupIDs?: optional list` (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. - `serviceTiers?: optional list` (query parameter) Filter to specific service tiers. Use `group_by[]=service_tier` to break out per-tier values. Claude Developer Platform organizations only; matches nothing for a Claude Enterprise organization. - `sessionIDs?: optional list` (query parameter) Filter to usage incurred by specific Claude Managed Agents sessions, by tagged session ID (`sesn_...`). Use `group_by[]=session_id` to break out per-session values. Claude Developer Platform organizations only. - `slackChannelIDs?: optional list` (query parameter) Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values. - `speeds?: optional list` (query parameter) Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values. - `timeBucketWidth?: optional AnalyticsTimeBucketWidth` (query parameter) Time-bucket granularity. When set, rows are returned per time bucket (one per bucket and dimension combination with usage) and each row's `starting_at` and `ending_at` are that bucket's bounds; the time bucket counts toward `limit`. `ending_at` is required when `time_bucket_width` is set, and with `time_bucket_width="1m"` the range may span at most 24 hours. When omitted, each row aggregates the requested range with `starting_at` and `ending_at` each rounded down to the hour. - `userProfileIDs?: optional list` (query parameter) Filter to usage attributed to specific user profiles, by tagged user profile ID (`uprof_...`). Use `group_by[]=user_profile_id` to break out per-profile values. Claude Developer Platform organizations only. - `workspaceIDs?: optional list` (query parameter) Filter to usage in specific workspaces, by tagged workspace ID (`wrkspc_...`). Use `group_by[]=workspace_id` to break out per-workspace values. Claude Developer Platform organizations only; matches nothing for a Claude Enterprise organization. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `analytics-usage-cost-2026-08-24` in this header. #### Returns - `class BetaAnalyticsCostItem` - `BetaAnalyticsCostMetrics cost` Cost for this row. - `\Datetime endingAt` End of the period this row covers (exclusive), as an RFC 3339 UTC timestamp: the end of the row's time bucket when a time-bucket width is set; otherwise the requested `ending_at` (or, when omitted, the earlier of now and `starting_at` plus 31 days) rounded down to the hour, because without a time bucket the report covers whole hours. - `BetaAnalyticsCostGroup group` The dimension values this row's cost is broken out by. - `\Datetime startingAt` Start of the period this row covers (inclusive), as an RFC 3339 UTC timestamp: the start of the row's time bucket when a time-bucket width is set, otherwise the requested `starting_at` rounded down to the hour. #### Example ```php beta->organization->analytics->cost->list( startingAt: new \DateTimeImmutable('2026-09-01T00:00:00Z'), actorIDs: ['user_01WxYzAbCdEfGhJkMnPqRsTu'], actorTypes: [AnalyticsActorType::SERVICE_ACCOUNT_ACTOR], agentIDs: ['agent_01VHd3EAGJ6PLkP9LM7DDu3f'], apiKeyIDs: ['apikey_01Rj2N8SVvo6BePZj99NhmiT'], claudeTagCategories: [AnalyticsClaudeTagCategory::ENGAGED], claudeTagUserIDs: ['U0123ABCDEF'], contextWindows: [AnalyticsContextWindow::FROM_0_TO_200K], deploymentIDs: ['depl_01JFC6ihzZHtAuyHsaENdJhY'], endingAt: new \DateTimeImmutable('2026-10-01T00:00:00Z'), environmentIDs: ['env_017oTjuGedHtjhJauVC5xGJD'], excludeDeletedUsers: true, groupBy: [BetaAnalyticsCostGroupBy::ACTOR], inferenceGeos: [AnalyticsInferenceGeoFilter::GLOBAL], limit: 1, models: ['string'], order: AnalyticsUsageCostSortOrder::ASC, orderBy: BetaAnalyticsCostOrderBy::AMOUNT, page: 'page', products: [AnalyticsUsageCostProductFilter::CHAT], rbacGroupIDs: ['rbac_group_012rppKaSVsmTo6NqRDXQXNF'], serviceTiers: [AnalyticsServiceTier::BATCH], sessionIDs: ['sesn_0187kPDyNCwibNNvfaPEApCJ'], slackChannelIDs: ['C0123ABCDEF'], speeds: [AnalyticsSpeed::FAST], timeBucketWidth: AnalyticsTimeBucketWidth::DAY, userProfileIDs: ['uprof_01M33NeYUQK2WV9PpYcsPHLi'], workspaceIDs: ['wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ'], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "cost": { "amount": "41280.000000", "currency": "USD", "list_amount": "51600.000000", "requests": 128 }, "ending_at": "2026-10-01T00:00:00Z", "group": { "actor": { "deleted": false, "email_address": "user@emaildomain.com", "name": "Jane Doe", "type": "user_actor", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "actor_type": "user_actor", "agent_id": "agent_01VHd3EAGJ6PLkP9LM7DDu3f", "api_key_id": "apikey_01Rj2N8SVvo6BePZj99NhmiT", "claude_tag_category": "dm", "claude_tag_user_id": "U0123ABCDEF", "context_window": "0-200k", "cost_type": "tokens", "deployment_id": "depl_01JFC6ihzZHtAuyHsaENdJhY", "environment_id": "env_017oTjuGedHtjhJauVC5xGJD", "inference_geo": "global", "model": "claude-opus-5-5", "product": "chat", "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "service_tier": "standard", "session_id": "sesn_0187kPDyNCwibNNvfaPEApCJ", "slack_channel_id": "C0123ABCDEF", "speed": "fast", "token_type": "cache_creation.ephemeral_1h_input_tokens", "user_profile_id": "uprof_01M33NeYUQK2WV9PpYcsPHLi", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" }, "starting_at": "2026-09-01T00:00:00Z" } ], "data_refreshed_at": "2026-10-01T04:02:11Z", "has_more": true, "next_page": "next_page" } ``` ## Beta › Organization › Analytics › Usage Report ### Get Token Usage Over Time `$client->beta->organization->analytics->usageReport->list(\Datetime startingAt, ?BucketWidth bucketWidth, ?list claudeTagCategories, ?list claudeTagUserIDs, ?list contextWindows, ?\Datetime endingAt, ?list groupBy, ?list inferenceGeos, ?int limit, ?list models, ?string page, ?list products, ?list rbacGroupIDs, ?list slackChannelIDs, ?list speeds, ?list userIDs): ReportPageCursor` **GET** `/v1/organizations/analytics/usage_report` [Legacy] Get token usage over time across a date range. Returns token usage bucketed by minute, hour, or day, optionally broken down by one or more `group_by[]` dimensions, such as product or model. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope. This endpoint is one of the legacy Claude Enterprise usage and cost reports. For new integrations, use [`GET /v1/organizations/analytics/usage`](https://platform.claude.com/docs/en/api/beta/organization/analytics/usage/list?sdk_languages=php) in the Usage and Cost Analytics API instead. To move an existing integration, see [Migrate from the Claude Enterprise usage and cost reports](https://platform.claude.com/docs/en/manage-claude/usage-cost-analytics-api?sdk_languages=php#migrate-from-enterprise-analytics-reports). #### Parameters - `startingAt: \Datetime` (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. - `bucketWidth?: optional BucketWidth` (query parameter) Time bucket granularity. default: 1d - `claudeTagCategories?: optional list` (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. - `claudeTagUserIDs?: optional list` (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. - `contextWindows?: optional list` (query parameter) Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values. - `endingAt?: optional \Datetime` (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. - `groupBy?: optional list` (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. - `inferenceGeos?: optional list` (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. - `limit?: optional int` (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). - `models?: optional list` (query parameter) Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values. - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `products?: optional list` (query parameter) Product surfaces to include. Defaults to all products. Use `group_by[]=product` to break out per-product values. - `rbacGroupIDs?: optional list` (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. - `slackChannelIDs?: optional list` (query parameter) Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values. - `speeds?: optional list` (query parameter) Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values. - `userIDs?: optional list` (query parameter) Filter to specific users by tagged user ID. #### Returns - `class AnalyticsUsageReportTimeBucket` - `\Datetime endingAt` End of the time bucket (exclusive) in RFC 3339 format. - `list results` 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). - `\Datetime startingAt` Start of the time bucket (inclusive) in RFC 3339 format. #### Example ```php beta->organization->analytics->usageReport->list( startingAt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), bucketWidth: '1d', claudeTagCategories: [AnalyticsClaudeTagCategory::ENGAGED], claudeTagUserIDs: ['U0123ABCDEF'], contextWindows: [AnalyticsContextWindow::FROM_0_TO_200K], endingAt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), groupBy: ['claude_tag_category'], inferenceGeos: [AnalyticsInferenceGeoFilter::GLOBAL], limit: 1, models: ['string'], page: 'page', products: [AnalyticsProductFilter::CHAT], rbacGroupIDs: ['rbac_group_012rppKaSVsmTo6NqRDXQXNF'], slackChannelIDs: ['C0123ABCDEF'], speeds: ['fast'], userIDs: ['string'], ); var_dump($page); ``` ##### 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 `$client->beta->organization->analytics->userUsageReport->list(\Datetime startingAt, ?BucketWidth bucketWidth, ?list claudeTagCategories, ?list claudeTagUserIDs, ?list contextWindows, ?\Datetime endingAt, ?bool excludeDeletedUsers, ?list groupBy, ?list inferenceGeos, ?int limit, ?list models, ?Order order, ?OrderBy orderBy, ?string page, ?list products, ?list rbacGroupIDs, ?list slackChannelIDs, ?list speeds, ?list userIDs): ReportPageCursor` **GET** `/v1/organizations/analytics/user_usage_report` [Legacy] Get per-user token usage across a date range. Returns usage per user, ranked by the chosen token metric; `group_by[]` or `bucket_width` splits a user across several rows. Use this to see which users consume the most tokens. Only usage attributed to a user account is included; usage with no user attributed to it, such as Code Review usage and Claude Tag usage in Slack channels, is left out. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope. This endpoint is one of the legacy Claude Enterprise usage and cost reports. For new integrations, use [`GET /v1/organizations/analytics/usage`](https://platform.claude.com/docs/en/api/beta/organization/analytics/usage/list?sdk_languages=php) in the Usage and Cost Analytics API instead. To move an existing integration, see [Migrate from the Claude Enterprise usage and cost reports](https://platform.claude.com/docs/en/manage-claude/usage-cost-analytics-api?sdk_languages=php#migrate-from-enterprise-analytics-reports). #### Parameters - `startingAt: \Datetime` (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. - `bucketWidth?: optional BucketWidth` (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. - `claudeTagCategories?: optional list` (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. - `claudeTagUserIDs?: optional list` (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. - `contextWindows?: optional list` (query parameter) Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values. - `endingAt?: optional \Datetime` (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. - `excludeDeletedUsers?: optional bool` (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. default: false - `groupBy?: optional list` (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. - `inferenceGeos?: optional list` (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. - `limit?: optional int` (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. default: 20 - `models?: optional list` (query parameter) Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values. - `order?: optional Order` (query parameter) Sort direction. Defaults to `desc`. default: desc - `orderBy?: optional OrderBy` (query parameter) Metric to rank actors by. Defaults to `total_tokens`. default: total_tokens - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `products?: optional list` (query parameter) Product surfaces to include. Defaults to all products. - `rbacGroupIDs?: optional list` (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. - `slackChannelIDs?: optional list` (query parameter) Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values. - `speeds?: optional list` (query parameter) Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values. - `userIDs?: optional list` (query parameter) Filter to specific users by tagged user ID. #### Returns - `class AnalyticsUsageUsersItem` - `AnalyticsUserActor actor` The user this row's usage or cost is attributed to. Always a `user_actor`. - `BetaCacheCreation cacheCreation` The number of input tokens for cache creation. - `int cacheReadInputTokens` The number of input tokens read from the cache. - `?AnalyticsClaudeTagCategory claudeTagCategory` 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. - `?string claudeTagUserID` 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. - `?AnalyticsContextWindow contextWindow` 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. - `?\Datetime endingAt` 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. - `?InferenceGeo inferenceGeo` 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). - `?string model` 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. - `int outputTokens` The number of output tokens generated. - `?string product` 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 where Chat and Cowork unified is available. Some unattributed usage is reported as "other". - `?string rbacGroupID` 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[]`. - `?int requests` 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`). - `AnalyticsServerToolUse serverToolUse` Server-side tool usage metrics. - `?string slackChannelID` 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 speed` Inference speed mode of the usage or cost: `fast` or `standard`. Null unless `speed` is in `group_by[]`. - `?\Datetime startingAt` 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. - `int totalTokens` Total token count across all token types. This is the value the default `order_by` (`total_tokens`) sorts on. - `int uncachedInputTokens` The number of uncached input tokens processed. #### Example ```php beta->organization->analytics->userUsageReport->list( startingAt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), bucketWidth: '1d', claudeTagCategories: [AnalyticsClaudeTagCategory::ENGAGED], claudeTagUserIDs: ['U0123ABCDEF'], contextWindows: [AnalyticsContextWindow::FROM_0_TO_200K], endingAt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), excludeDeletedUsers: true, groupBy: ['claude_tag_category'], inferenceGeos: [AnalyticsInferenceGeoFilter::GLOBAL], limit: 1, models: ['string'], order: 'asc', orderBy: 'output_tokens', page: 'page', products: [AnalyticsProductFilter::CHAT], rbacGroupIDs: ['rbac_group_012rppKaSVsmTo6NqRDXQXNF'], slackChannelIDs: ['C0123ABCDEF'], speeds: ['fast'], userIDs: ['user_01AbCdEfGhIjKlMnOpQrSt'], ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "actor": { "deleted": true, "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 `$client->beta->organization->analytics->costReport->list(\Datetime startingAt, ?BucketWidth bucketWidth, ?list claudeTagCategories, ?list claudeTagUserIDs, ?list contextWindows, ?\Datetime endingAt, ?list groupBy, ?list inferenceGeos, ?int limit, ?list models, ?string page, ?list products, ?list rbacGroupIDs, ?list slackChannelIDs, ?list speeds, ?list userIDs): ReportPageCursor` **GET** `/v1/organizations/analytics/cost_report` [Legacy] Get cost in USD over time across a date range. Returns cost bucketed by minute, hour, or day, optionally broken down by one or more `group_by[]` dimensions, such as model or cost type. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope. This endpoint is one of the legacy Claude Enterprise usage and cost reports. For new integrations, use [`GET /v1/organizations/analytics/cost`](https://platform.claude.com/docs/en/api/beta/organization/analytics/cost/list?sdk_languages=php) in the Usage and Cost Analytics API instead. To move an existing integration, see [Migrate from the Claude Enterprise usage and cost reports](https://platform.claude.com/docs/en/manage-claude/usage-cost-analytics-api?sdk_languages=php#migrate-from-enterprise-analytics-reports). #### Parameters - `startingAt: \Datetime` (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. - `bucketWidth?: optional BucketWidth` (query parameter) Time bucket granularity. default: 1d - `claudeTagCategories?: optional list` (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. - `claudeTagUserIDs?: optional list` (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. - `contextWindows?: optional list` (query parameter) Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values. - `endingAt?: optional \Datetime` (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. - `groupBy?: optional list` (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. - `inferenceGeos?: optional list` (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. - `limit?: optional int` (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). - `models?: optional list` (query parameter) Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values. - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `products?: optional list` (query parameter) Product surfaces to include. Defaults to all products. Use `group_by[]=product` to break out per-product values. - `rbacGroupIDs?: optional list` (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. - `slackChannelIDs?: optional list` (query parameter) Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values. - `speeds?: optional list` (query parameter) Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values. - `userIDs?: optional list` (query parameter) Filter to specific users by tagged user ID. #### Returns - `class AnalyticsCostReportTimeBucket` - `\Datetime endingAt` End of the time bucket (exclusive) in RFC 3339 format. - `list results` 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). - `\Datetime startingAt` Start of the time bucket (inclusive) in RFC 3339 format. #### Example ```php beta->organization->analytics->costReport->list( startingAt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), bucketWidth: '1d', claudeTagCategories: [AnalyticsClaudeTagCategory::ENGAGED], claudeTagUserIDs: ['U0123ABCDEF'], contextWindows: [AnalyticsContextWindow::FROM_0_TO_200K], endingAt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), groupBy: ['claude_tag_category'], inferenceGeos: [AnalyticsInferenceGeoFilter::GLOBAL], limit: 1, models: ['string'], page: 'page', products: [AnalyticsProductFilter::CHAT], rbacGroupIDs: ['rbac_group_012rppKaSVsmTo6NqRDXQXNF'], slackChannelIDs: ['C0123ABCDEF'], speeds: ['fast'], userIDs: ['string'], ); var_dump($page); ``` ##### 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 `$client->beta->organization->analytics->userCostReport->list(\Datetime startingAt, ?BucketWidth bucketWidth, ?list claudeTagCategories, ?list claudeTagUserIDs, ?list contextWindows, ?\Datetime endingAt, ?bool excludeDeletedUsers, ?list groupBy, ?list inferenceGeos, ?int limit, ?list models, ?Order order, ?OrderBy orderBy, ?string page, ?list products, ?list rbacGroupIDs, ?list slackChannelIDs, ?list speeds, ?list userIDs): ReportPageCursor` **GET** `/v1/organizations/analytics/user_cost_report` [Legacy] Get per-user cost in USD across a date range. Returns cost per user, ranked by spend; `group_by[]` or `bucket_width` splits a user across several rows. Use this to see which users account for the most cost. Only cost attributed to a user account is included; cost with no user attributed to it, such as Code Review usage and Claude Tag usage in Slack channels, is left out. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope. This endpoint is one of the legacy Claude Enterprise usage and cost reports. For new integrations, use [`GET /v1/organizations/analytics/cost`](https://platform.claude.com/docs/en/api/beta/organization/analytics/cost/list?sdk_languages=php) in the Usage and Cost Analytics API instead. To move an existing integration, see [Migrate from the Claude Enterprise usage and cost reports](https://platform.claude.com/docs/en/manage-claude/usage-cost-analytics-api?sdk_languages=php#migrate-from-enterprise-analytics-reports). #### Parameters - `startingAt: \Datetime` (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. - `bucketWidth?: optional BucketWidth` (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. - `claudeTagCategories?: optional list` (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. - `claudeTagUserIDs?: optional list` (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. - `contextWindows?: optional list` (query parameter) Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values. - `endingAt?: optional \Datetime` (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. - `excludeDeletedUsers?: optional bool` (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. default: false - `groupBy?: optional list` (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. - `inferenceGeos?: optional list` (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. - `limit?: optional int` (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. default: 20 - `models?: optional list` (query parameter) Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values. - `order?: optional Order` (query parameter) Sort direction. Defaults to `desc`. default: desc - `orderBy?: optional OrderBy` (query parameter) Metric to rank actors by. Defaults to `amount`. default: amount - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `products?: optional list` (query parameter) Product surfaces to include. Defaults to all products. - `rbacGroupIDs?: optional list` (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. - `slackChannelIDs?: optional list` (query parameter) Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values. - `speeds?: optional list` (query parameter) Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values. - `userIDs?: optional list` (query parameter) Filter to specific users by tagged user ID. #### Returns - `class AnalyticsCostUsersItem` - `AnalyticsUserActor actor` The user this row's usage or cost is attributed to. Always a `user_actor`. - `string amount` Amount (post-discount, pre-credit) in fractional cents (minor units). - `?AnalyticsClaudeTagCategory claudeTagCategory` 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. - `?string claudeTagUserID` 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. - `?AnalyticsContextWindow contextWindow` 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. - `?AnalyticsCostType costType` Cost component breakdown; null when returning the combined total. - `string currency` Currency code for the cost amount. Currently always `"USD"`. - `?\Datetime endingAt` 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. - `?InferenceGeo inferenceGeo` 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). - `string listAmount` List-price amount (pre-discount) in fractional cents. - `?string model` 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. - `?string product` 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 where Chat and Cowork unified is available. Some unattributed usage is reported as "other". - `?string rbacGroupID` 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[]`. - `?int requests` 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`). - `?string slackChannelID` 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 speed` Inference speed mode of the usage or cost: `fast` or `standard`. Null unless `speed` is in `group_by[]`. - `?\Datetime startingAt` 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. - `?AnalyticsTokenType tokenType` Token type when `cost_type` is `tokens`; null otherwise. #### Example ```php beta->organization->analytics->userCostReport->list( startingAt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), bucketWidth: '1d', claudeTagCategories: [AnalyticsClaudeTagCategory::ENGAGED], claudeTagUserIDs: ['U0123ABCDEF'], contextWindows: [AnalyticsContextWindow::FROM_0_TO_200K], endingAt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), excludeDeletedUsers: true, groupBy: ['claude_tag_category'], inferenceGeos: [AnalyticsInferenceGeoFilter::GLOBAL], limit: 1, models: ['string'], order: 'asc', orderBy: 'amount', page: 'page', products: [AnalyticsProductFilter::CHAT], rbacGroupIDs: ['rbac_group_012rppKaSVsmTo6NqRDXQXNF'], slackChannelIDs: ['C0123ABCDEF'], speeds: ['fast'], userIDs: ['user_01AbCdEfGhIjKlMnOpQrSt'], ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "actor": { "deleted": true, "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 `$client->beta->organization->spendLimits->set(?string amount, Scope scope, ?SpendLimitPeriod period, ?list betas): SpendLimit` **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: Scope` 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 SpendLimitPeriod` - `betas?: optional list` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `class SpendLimit` - `"spend_limit" type` Object type. Always `spend_limit`. - `string id` Unique tagged ID of the spend limit (`spl_...`). - `?string amount` 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. - `\Datetime createdAt` RFC 3339 datetime at which the spend limit was created. - `string currency` ISO 4217 code of the organization's billing currency; the unit for `amount`. - `bool isEnabled` 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. - `SpendLimitPeriod period` Length of the window the limit resets over. `amount` caps spend within each period. - `Scope scope` What the limit applies to. A tagged union on `type`; each variant carries the identifier for its scope. - `\Datetime updatedAt` RFC 3339 datetime at which the spend limit was last modified. #### Example ```php beta->organization->spendLimits->set( amount: '50000', scope: ['type' => 'user', 'userID' => 'user_01WxYzAbCdEfGhJkMnPqRsTu'], period: SpendLimitPeriod::MONTHLY, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaSpendLimit); ``` ##### 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_01WxYzAbCdEfGhJkMnPqRsTu" }, "type": "spend_limit", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ### Get Spend Limit `$client->beta->organization->spendLimits->retrieve(string spendLimitID): SpendLimit` **GET** `/v1/organizations/spend_limits/{spend_limit_id}` Retrieve a spend limit by ID. #### Parameters - `spendLimitID: string` (path parameter) ID of the Spend Limit. #### Returns - `class SpendLimit` - `"spend_limit" type` Object type. Always `spend_limit`. - `string id` Unique tagged ID of the spend limit (`spl_...`). - `?string amount` 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. - `\Datetime createdAt` RFC 3339 datetime at which the spend limit was created. - `string currency` ISO 4217 code of the organization's billing currency; the unit for `amount`. - `bool isEnabled` 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. - `SpendLimitPeriod period` Length of the window the limit resets over. `amount` caps spend within each period. - `Scope scope` What the limit applies to. A tagged union on `type`; each variant carries the identifier for its scope. - `\Datetime updatedAt` RFC 3339 datetime at which the spend limit was last modified. #### Example ```php beta->organization->spendLimits->retrieve( 'spend_limit_id' ); var_dump($betaSpendLimit); ``` ##### 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_01WxYzAbCdEfGhJkMnPqRsTu" }, "type": "spend_limit", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ### Delete Spend Limit `$client->beta->organization->spendLimits->delete(string spendLimitID): SpendLimitDeleteResponse` **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 - `spendLimitID: string` (path parameter) ID of the Spend Limit. #### Returns - `class SpendLimitDeleteResponse` - `"spend_limit_deleted" type` - `string id` #### Example ```php beta->organization->spendLimits->delete( 'spend_limit_id' ); var_dump($spendLimit); ``` ##### Response (200) ```json { "id": "id", "type": "spend_limit_deleted" } ``` ### List Spend Limits `$client->beta->organization->spendLimits->list(?int limit, ?string page, ?list scopeType, ?string workspaceID, ?list betas): PageCursor` **GET** `/v1/organizations/spend_limits` List the organization's spend limits. A Claude Console organization's limits, including any read-only `usage_tier` limit, come newest first. Listing them is in an early access preview. To request access, contact your Anthropic account team. A Claude Enterprise organization's 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. #### Parameters - `limit?: optional int` (query parameter) Maximum number of limits per page. Defaults to `20`. default: 20 - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `scopeType?: optional list` (query parameter) Return only limits with these scope types. Omit for all. A scope type that doesn't apply to the organization gets a 400 error. - `workspaceID?: optional string` (query parameter) Return only the limits whose `scope.workspace_id` is this workspace (`wrkspc_...`). Claude Console organizations only; other organizations get a 400 error. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `spend-limit-reads-2026-09-26` in this header. #### Returns - `class SpendLimit` - `"spend_limit" type` Object type. Always `spend_limit`. - `string id` Unique tagged ID of the spend limit (`spl_...`). - `?string amount` 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. - `\Datetime createdAt` RFC 3339 datetime at which the spend limit was created. - `string currency` ISO 4217 code of the organization's billing currency; the unit for `amount`. - `bool isEnabled` 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. - `SpendLimitPeriod period` Length of the window the limit resets over. `amount` caps spend within each period. - `Scope scope` What the limit applies to. A tagged union on `type`; each variant carries the identifier for its scope. - `\Datetime updatedAt` RFC 3339 datetime at which the spend limit was last modified. #### Example ```php beta->organization->spendLimits->list( limit: 1, page: 'page', scopeType: ['organization'], workspaceID: 'workspace_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### 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_01WxYzAbCdEfGhJkMnPqRsTu" }, "type": "spend_limit", "updated_at": "2019-12-27T18:11:19.117Z" } ], "next_page": "next_page" } ``` ## Beta › Organization › Spend Limits › Effective ### List Effective Spend Limits `$client->beta->organization->spendLimits->effective->list(?int limit, ?string page, ?list period, ?list userIDs): PageCursor` **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 int` (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`. default: 20 - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `period?: optional list` (query parameter) Restrict the report to these limit periods. Omit to return one row per period each member resolves a spend limit for. - `userIDs?: optional list` (query parameter) Restrict the report to these members, by tagged user ID (`user_...`). At most 100 entries. #### Returns - `class SpendSummary` - `Actor actor` - `?string amount` 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. - `string currency` ISO 4217 code of the organization's billing currency; the unit for `amount` and `period_to_date_spend`. - `SpendLimitPeriod period` Period this row's effective limit and spend are reported for. - `string periodToDateSpend` 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 scope` - `Source source` - `string spendLimitID` #### Example ```php beta->organization->spendLimits->effective->list( limit: 1, page: 'page', period: [SpendLimitPeriod::DAILY], userIDs: ['string'] ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "actor": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "amount": "50000", "currency": "USD", "period": "daily", "period_to_date_spend": "12050.5", "scope": { "type": "user", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "source": { "type": "user", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "spend_limit_id": "spend_limit_id" } ], "next_page": "next_page" } ``` ## Beta › Organization › Spend Limits › Increase Requests ### List Spend Limit Increase Requests `$client->beta->organization->spendLimits->increaseRequests->list(?list actorIDs, ?int limit, ?string page, ?list status): PageCursor` **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 - `actorIDs?: optional list` (query parameter) Filter by requester, as `user_...` tagged IDs. - `limit?: optional int` (query parameter) default: 20 - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. - `status?: optional list` (query parameter) Filter by status. Omit to return all. #### Returns - `class BetaSpendLimitIncreaseRequest` - `"spend_limit_increase_request" type` - `string id` - `BetaSpendLimitIncreaseRequestActor actor` Who submitted the increase request. - `\Datetime createdAt` - `SpendLimitPeriod period` - `?\Datetime resolvedAt` - `?BetaSpendLimitIncreaseRequestResolvedBy resolvedBy` Who approved or denied the increase request. - `?SpendSummary spendSummary` Per-member effective-limit report row (`GET /spend_limits/effective`). - `BetaSpendLimitIncreaseRequestStatus status` #### Example ```php beta->organization->spendLimits->increaseRequests->list( actorIDs: ['string'], limit: 1, page: 'page', status: [BetaSpendLimitIncreaseRequestStatus::APPROVED], ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "id": "id", "actor": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "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_01WxYzAbCdEfGhJkMnPqRsTu" }, "spend_summary": { "actor": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "amount": "50000", "currency": "USD", "period": "daily", "period_to_date_spend": "12050.5", "scope": { "type": "user", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "source": { "type": "user", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "spend_limit_id": "spend_limit_id" }, "status": "approved", "type": "spend_limit_increase_request" } ], "next_page": "next_page" } ``` ### Get Spend Limit Increase Request `$client->beta->organization->spendLimits->increaseRequests->retrieve(string spendLimitIncreaseRequestID): BetaSpendLimitIncreaseRequest` **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 - `spendLimitIncreaseRequestID: string` (path parameter) ID of the spend limit increase request. #### Returns - `class BetaSpendLimitIncreaseRequest` - `"spend_limit_increase_request" type` - `string id` - `BetaSpendLimitIncreaseRequestActor actor` Who submitted the increase request. - `\Datetime createdAt` - `SpendLimitPeriod period` - `?\Datetime resolvedAt` - `?BetaSpendLimitIncreaseRequestResolvedBy resolvedBy` Who approved or denied the increase request. - `?SpendSummary spendSummary` Per-member effective-limit report row (`GET /spend_limits/effective`). - `BetaSpendLimitIncreaseRequestStatus status` #### Example ```php beta ->organization ->spendLimits ->increaseRequests ->retrieve('spend_limit_increase_request_id'); var_dump($betaSpendLimitIncreaseRequest); ``` ##### Response (200) ```json { "id": "id", "actor": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "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_01WxYzAbCdEfGhJkMnPqRsTu" }, "spend_summary": { "actor": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "amount": "50000", "currency": "USD", "period": "daily", "period_to_date_spend": "12050.5", "scope": { "type": "user", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "source": { "type": "user", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "spend_limit_id": "spend_limit_id" }, "status": "approved", "type": "spend_limit_increase_request" } ``` ### Approve Spend Limit Increase Request `$client->beta->organization->spendLimits->increaseRequests->approve(string spendLimitIncreaseRequestID, string amount, ?SpendLimitPeriod period, ?bool suppressNotification): IncreaseRequestApproveResponse` **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 - `spendLimitIncreaseRequestID: 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 SpendLimitPeriod` - `suppressNotification?: optional bool` #### Returns - `class IncreaseRequestApproveResponse` - `"spend_limit_increase_request" type` - `string id` - `BetaSpendLimitIncreaseRequestActor actor` Who submitted the increase request. - `\Datetime createdAt` - `SpendLimitPeriod period` - `?\Datetime resolvedAt` - `?BetaSpendLimitIncreaseRequestResolvedBy resolvedBy` Who approved or denied the increase request. - `?SpendLimit spendLimit` A configured spend limit: a cap on metered spend for one scope and period. - `?SpendSummary spendSummary` Per-member effective-limit report row (`GET /spend_limits/effective`). - `BetaSpendLimitIncreaseRequestStatus status` #### Example ```php beta->organization->spendLimits->increaseRequests->approve( 'spend_limit_increase_request_id', amount: '50000', period: SpendLimitPeriod::MONTHLY, suppressNotification: true, ); var_dump($response); ``` ##### Response (200) ```json { "id": "id", "actor": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "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_01WxYzAbCdEfGhJkMnPqRsTu" }, "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_01WxYzAbCdEfGhJkMnPqRsTu" }, "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_01WxYzAbCdEfGhJkMnPqRsTu" }, "amount": "50000", "currency": "USD", "period": "daily", "period_to_date_spend": "12050.5", "scope": { "type": "user", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "source": { "type": "user", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "spend_limit_id": "spend_limit_id" }, "status": "approved", "type": "spend_limit_increase_request" } ``` ### Deny Spend Limit Increase Request `$client->beta->organization->spendLimits->increaseRequests->deny(string spendLimitIncreaseRequestID, ?bool suppressNotification): BetaSpendLimitIncreaseRequest` **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 - `spendLimitIncreaseRequestID: string` (path parameter) ID of the spend limit increase request. - `suppressNotification?: optional bool` #### Returns - `class BetaSpendLimitIncreaseRequest` - `"spend_limit_increase_request" type` - `string id` - `BetaSpendLimitIncreaseRequestActor actor` Who submitted the increase request. - `\Datetime createdAt` - `SpendLimitPeriod period` - `?\Datetime resolvedAt` - `?BetaSpendLimitIncreaseRequestResolvedBy resolvedBy` Who approved or denied the increase request. - `?SpendSummary spendSummary` Per-member effective-limit report row (`GET /spend_limits/effective`). - `BetaSpendLimitIncreaseRequestStatus status` #### Example ```php beta ->organization ->spendLimits ->increaseRequests ->deny('spend_limit_increase_request_id', suppressNotification: true); var_dump($betaSpendLimitIncreaseRequest); ``` ##### Response (200) ```json { "id": "id", "actor": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "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_01WxYzAbCdEfGhJkMnPqRsTu" }, "spend_summary": { "actor": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "amount": "50000", "currency": "USD", "period": "daily", "period_to_date_spend": "12050.5", "scope": { "type": "user", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "source": { "type": "user", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "spend_limit_id": "spend_limit_id" }, "status": "approved", "type": "spend_limit_increase_request" } ``` ## Beta › Organization › RBAC Groups ### Create RBAC Group `$client->beta->organization->rbacGroups->create(string name): RBACGroup` **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. #### Returns - `class RBACGroup` - `"rbac_group" type` Object type. For RBAC Groups, this is always `"rbac_group"`. - `string id` ID of the RBAC Group. - `\Datetime createdAt` RFC 3339 timestamp of when the RBAC Group was created. - `string name` Name of the RBAC Group. Not uniqueness-enforced. - `?list roleIDs` 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. - `SourceType sourceType` 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. - `\Datetime updatedAt` RFC 3339 timestamp of when the RBAC Group was last updated. #### Example ```php beta->organization->rbacGroups->create( name: 'Engineering' ); var_dump($betaRBACGroup); ``` ##### Response (200) ```json { "id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "created_at": "2024-10-30T23:58:27.427722Z", "name": "Engineering", "role_ids": [ "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s" ], "source_type": "direct", "type": "rbac_group", "updated_at": "2024-10-30T23:58:27.427722Z" } ``` ### List RBAC Groups `$client->beta->organization->rbacGroups->list(?int limit, ?string page): PageCursor` **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 int` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. default: 20 - `page?: optional string` (query parameter) Optionally set to the `next_page` token from the previous response. #### Returns - `class RBACGroup` - `"rbac_group" type` Object type. For RBAC Groups, this is always `"rbac_group"`. - `string id` ID of the RBAC Group. - `\Datetime createdAt` RFC 3339 timestamp of when the RBAC Group was created. - `string name` Name of the RBAC Group. Not uniqueness-enforced. - `?list roleIDs` 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. - `SourceType sourceType` 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. - `\Datetime updatedAt` RFC 3339 timestamp of when the RBAC Group was last updated. #### Example ```php beta->organization->rbacGroups->list( limit: 1, page: 'eyJjdXJzb3IiOiAicmJhY19ncm91cF8wMSJ9' ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "created_at": "2024-10-30T23:58:27.427722Z", "name": "Engineering", "role_ids": [ "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 `$client->beta->organization->rbacGroups->retrieve(string rbacGroupID): RBACGroup` **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 - `rbacGroupID: string` (path parameter) ID of the RBAC Group. #### Returns - `class RBACGroup` - `"rbac_group" type` Object type. For RBAC Groups, this is always `"rbac_group"`. - `string id` ID of the RBAC Group. - `\Datetime createdAt` RFC 3339 timestamp of when the RBAC Group was created. - `string name` Name of the RBAC Group. Not uniqueness-enforced. - `?list roleIDs` 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. - `SourceType sourceType` 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. - `\Datetime updatedAt` RFC 3339 timestamp of when the RBAC Group was last updated. #### Example ```php beta->organization->rbacGroups->retrieve( 'rbac_group_id' ); var_dump($betaRBACGroup); ``` ##### Response (200) ```json { "id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "created_at": "2024-10-30T23:58:27.427722Z", "name": "Engineering", "role_ids": [ "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s" ], "source_type": "direct", "type": "rbac_group", "updated_at": "2024-10-30T23:58:27.427722Z" } ``` ### Update RBAC Group `$client->beta->organization->rbacGroups->update(string rbacGroupID, ?string name): RBACGroup` **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 - `rbacGroupID: string` (path parameter) ID of the RBAC Group. - `name?: optional string` Name of the RBAC Group. Not uniqueness-enforced. #### Returns - `class RBACGroup` - `"rbac_group" type` Object type. For RBAC Groups, this is always `"rbac_group"`. - `string id` ID of the RBAC Group. - `\Datetime createdAt` RFC 3339 timestamp of when the RBAC Group was created. - `string name` Name of the RBAC Group. Not uniqueness-enforced. - `?list roleIDs` 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. - `SourceType sourceType` 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. - `\Datetime updatedAt` RFC 3339 timestamp of when the RBAC Group was last updated. #### Example ```php beta->organization->rbacGroups->update( 'rbac_group_id', name: 'Engineering' ); var_dump($betaRBACGroup); ``` ##### Response (200) ```json { "id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "created_at": "2024-10-30T23:58:27.427722Z", "name": "Engineering", "role_ids": [ "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s" ], "source_type": "direct", "type": "rbac_group", "updated_at": "2024-10-30T23:58:27.427722Z" } ``` ### Delete RBAC Group `$client->beta->organization->rbacGroups->delete(string rbacGroupID): DeletedRBACGroup` **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 - `rbacGroupID: string` (path parameter) ID of the RBAC Group. #### Returns - `class DeletedRBACGroup` - `"rbac_group_deleted" type` Deleted object type. For RBAC Groups, this is always `"rbac_group_deleted"`. - `string id` ID of the RBAC Group. #### Example ```php beta->organization->rbacGroups->delete( 'rbac_group_id' ); var_dump($betaDeletedRBACGroup); ``` ##### Response (200) ```json { "id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "type": "rbac_group_deleted" } ``` ## Beta › Organization › RBAC Groups › Members ### List RBAC Group Members `$client->beta->organization->rbacGroups->members->list(string rbacGroupID, ?int limit, ?string page): PageCursor` **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 - `rbacGroupID: string` (path parameter) ID of the RBAC Group. - `limit?: optional int` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. default: 20 - `page?: optional string` (query parameter) Optionally set to the `next_page` token from the previous response. #### Returns - `class BetaRBACGroupMember` - `"rbac_group_member" type` Object type. For RBAC Group Members, this is always `"rbac_group_member"`. - `\Datetime createdAt` RFC 3339 timestamp of when the User was added to the RBAC Group. - `string email` Email of the User. - `string rbacGroupID` ID of the RBAC Group. - `string userID` ID of the User. #### Example ```php beta->organization->rbacGroups->members->list( 'rbac_group_id', limit: 1, page: 'eyJjdXJzb3IiOiAicmJhY19ncm91cF8wMSJ9' ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "created_at": "2024-10-30T23:58:27.427722Z", "email": "user@emaildomain.com", "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "type": "rbac_group_member", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" } ], "has_more": false, "next_page": "eyJjdXJzb3IiOiAicmJhY19ncm91cF8wMSJ9" } ``` ### Add RBAC Group Member `$client->beta->organization->rbacGroups->members->add(string rbacGroupID, string userID): BetaRBACGroupMember` **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 - `rbacGroupID: string` (path parameter) ID of the RBAC Group. - `userID: string` ID of the User. #### Returns - `class BetaRBACGroupMember` - `"rbac_group_member" type` Object type. For RBAC Group Members, this is always `"rbac_group_member"`. - `\Datetime createdAt` RFC 3339 timestamp of when the User was added to the RBAC Group. - `string email` Email of the User. - `string rbacGroupID` ID of the RBAC Group. - `string userID` ID of the User. #### Example ```php beta->organization->rbacGroups->members->add( 'rbac_group_id', userID: 'user_01WxYzAbCdEfGhJkMnPqRsTu' ); var_dump($betaRBACGroupMember); ``` ##### Response (200) ```json { "created_at": "2024-10-30T23:58:27.427722Z", "email": "user@emaildomain.com", "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "type": "rbac_group_member", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" } ``` ### Remove RBAC Group Member `$client->beta->organization->rbacGroups->members->remove(string userID, string rbacGroupID): BetaDeletedRBACGroupMember` **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 - `rbacGroupID: string` (path parameter) ID of the RBAC Group. - `userID: string` (path parameter) ID of the User. #### Returns - `class BetaDeletedRBACGroupMember` - `"rbac_group_member_deleted" type` Deleted object type. For RBAC Group Members, this is always `"rbac_group_member_deleted"`. - `string rbacGroupID` ID of the RBAC Group. - `string userID` ID of the User. #### Example ```php beta ->organization ->rbacGroups ->members ->remove('user_id', rbacGroupID: 'rbac_group_id'); var_dump($betaDeletedRBACGroupMember); ``` ##### Response (200) ```json { "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "type": "rbac_group_member_deleted", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" } ``` ## Beta › Organization › RBAC Roles ### List RBAC Roles `$client->beta->organization->rbacRoles->list(?int limit, ?string page): PageCursor` **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 int` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. default: 20 - `page?: optional string` (query parameter) Optionally set to the `next_page` token from the previous response. #### Returns - `class RBACRole` - `"rbac_role" type` Object type. For RBAC Roles, this is always `"rbac_role"`. - `string id` ID of the RBAC Role. - `\Datetime createdAt` RFC 3339 datetime string indicating when the RBAC Role was created. - `string displayName` 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`. - `\Datetime updatedAt` RFC 3339 datetime string indicating when the RBAC Role was last updated. #### Example ```php beta->organization->rbacRoles->list( limit: 1, page: 'eyJjdXJzb3IiOiAicmJhY19yb2xlXzAxIn0' ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "id": "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s", "created_at": "2024-10-30T23:58:27.427722Z", "display_name": "Project Editor", "type": "rbac_role", "updated_at": "2024-10-30T23:58:27.427722Z" } ], "has_more": true, "next_page": "eyJjdXJzb3IiOiAicmJhY19yb2xlXzAxIn0" } ``` ### Get RBAC Role `$client->beta->organization->rbacRoles->retrieve(string rbacRoleID): RBACRole` **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 - `rbacRoleID: string` (path parameter) ID of the RBAC Role. #### Returns - `class RBACRole` - `"rbac_role" type` Object type. For RBAC Roles, this is always `"rbac_role"`. - `string id` ID of the RBAC Role. - `\Datetime createdAt` RFC 3339 datetime string indicating when the RBAC Role was created. - `string displayName` 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`. - `\Datetime updatedAt` RFC 3339 datetime string indicating when the RBAC Role was last updated. #### Example ```php beta->organization->rbacRoles->retrieve( 'rbac_role_id' ); var_dump($betaRBACRole); ``` ##### Response (200) ```json { "id": "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s", "created_at": "2024-10-30T23:58:27.427722Z", "display_name": "Project Editor", "type": "rbac_role", "updated_at": "2024-10-30T23:58:27.427722Z" } ``` ## Beta › Organization › RBAC Roles › Permissions ### List RBAC Role Permissions `$client->beta->organization->rbacRoles->permissions->list(string rbacRoleID, ?int limit, ?string page): PageCursor` **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 - `rbacRoleID: string` (path parameter) ID of the RBAC Role. - `limit?: optional int` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. default: 20 - `page?: optional string` (query parameter) Optionally set to the `next_page` token from the previous response. #### Returns - `class BetaRBACRolePermission` - `"rbac_role_permission" type` Object type. For RBAC Role Permissions, this is always `"rbac_role_permission"`. - `string action` 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 except `inference_hooks_inspection`, which a role holds only through its own row, and `capability_access_all_ga` grants the generally-available subset of those 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 resource` What the permission applies to. A tagged union: `type` names the kind of resource and determines which identifier fields are present. #### Example ```php beta->organization->rbacRoles->permissions->list( 'rbac_role_id', limit: 1, page: 'eyJjdXJzb3IiOiAicmJhY19yb2xlXzAxIn0' ); var_dump($page); ``` ##### 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 `$client->beta->organization->plugins->create(list files, ?string marketplaceID, ?string releaseNotes, ?list betas): Plugin` **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=php#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 - `files: list` 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`. - `marketplaceID?: 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. - `releaseNotes?: optional string` Release notes stored with the version and shown in its version history in claude.ai; up to 5,000 characters. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `class Plugin` - `"plugin" type` Always `plugin`. - `string id` The Plugin's ID. - `?list components` What the served version contains; null when not enumerated. - `?PluginContentScan contentScan` The served version's content scan; null when it has not been scanned. - `\Datetime createdAt` RFC 3339. - `?CreatedBy createdBy` Who created the Plugin; null when no creator is recorded. - `?string description` The served version's description. - `?string displayName` The served version's display name. - `string latestVersionID` The newest version. - `?string manifestVersion` The served version's manifest `version`, normalized for display, or `null` (the Plugin Version's `manifest_version` says how and when). - `string marketplaceID` The ID of the plugin marketplace the Plugin lives in. - `string name` 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. - `?OrganizationInstallationPreference organizationInstallationPreference` 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. - `?bool organizationInstallationPreferenceInherited` 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 owner` Who owns the Plugin: the organization, or the member whose personal plugin marketplace it lives in. - `?Reach reach` 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`. - `string servedVersionID` The version claude.ai serves to members. - `bool servedVersionPinned` True once the served version has been pinned, through Update Plugin or in claude.ai. While false, a new version normally becomes the served version when it is stored. While the newest version is not the served version, as when a version saved in claude.ai is waiting for its content scan, `served_version_id` differs from `latest_version_id`. - `\Datetime updatedAt` RFC 3339. Moves on a served-version change (including pinning an unpinned Plugin to the version it already serves) and, normally, on a new version. A version saved in claude.ai that waits for its content scan moves it when it becomes the served version, and not necessarily when it is stored. A change to the Plugin's installation settings or shares does not move it. #### Example ```php beta->organization->plugins->create( files: [ FileParam::fromString('Example data', filename: uniqid('file-upload-', true)), ], marketplaceID: 'marketplace_id', releaseNotes: 'release_notes', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaPlugin); ``` ##### 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_01WxYzAbCdEfGhJkMnPqRsTu" }, "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 `$client->beta->organization->plugins->retrieve(string pluginID, ?string organizationID, ?list betas): Plugin` **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 - `pluginID: string` (path parameter) ID of the Plugin (prefixed `plugin_`). - `organizationID?: 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. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `class Plugin` - `"plugin" type` Always `plugin`. - `string id` The Plugin's ID. - `?list components` What the served version contains; null when not enumerated. - `?PluginContentScan contentScan` The served version's content scan; null when it has not been scanned. - `\Datetime createdAt` RFC 3339. - `?CreatedBy createdBy` Who created the Plugin; null when no creator is recorded. - `?string description` The served version's description. - `?string displayName` The served version's display name. - `string latestVersionID` The newest version. - `?string manifestVersion` The served version's manifest `version`, normalized for display, or `null` (the Plugin Version's `manifest_version` says how and when). - `string marketplaceID` The ID of the plugin marketplace the Plugin lives in. - `string name` 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. - `?OrganizationInstallationPreference organizationInstallationPreference` 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. - `?bool organizationInstallationPreferenceInherited` 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 owner` Who owns the Plugin: the organization, or the member whose personal plugin marketplace it lives in. - `?Reach reach` 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`. - `string servedVersionID` The version claude.ai serves to members. - `bool servedVersionPinned` True once the served version has been pinned, through Update Plugin or in claude.ai. While false, a new version normally becomes the served version when it is stored. While the newest version is not the served version, as when a version saved in claude.ai is waiting for its content scan, `served_version_id` differs from `latest_version_id`. - `\Datetime updatedAt` RFC 3339. Moves on a served-version change (including pinning an unpinned Plugin to the version it already serves) and, normally, on a new version. A version saved in claude.ai that waits for its content scan moves it when it becomes the served version, and not necessarily when it is stored. A change to the Plugin's installation settings or shares does not move it. #### Example ```php beta->organization->plugins->retrieve( 'plugin_id', organizationID: 'organization_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaPlugin); ``` ##### 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_01WxYzAbCdEfGhJkMnPqRsTu" }, "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 `$client->beta->organization->plugins->update(string pluginID, string servedVersionID, ?list betas): Plugin` **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 `content_scan.status` is `processing` is refused with a 409 (`error_code` `scan_pending`; retry once the scan finishes). A version whose `content_scan.status` is `errored`, or whose `content_scan.assessment` is `fail` or `unknown`, is refused with a 400 (`error_code` `scan_failed`); a `warn` is accepted. If the scan outcome cannot be read at that moment, the request fails with a retryable 503 instead. 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 - `pluginID: string` (path parameter) ID of the Plugin (prefixed `plugin_`). - `servedVersionID: string` Serve this version of the Plugin (prefixed `pluginver_`) and pin the served version to it; `latest` is not accepted. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `class Plugin` - `"plugin" type` Always `plugin`. - `string id` The Plugin's ID. - `?list components` What the served version contains; null when not enumerated. - `?PluginContentScan contentScan` The served version's content scan; null when it has not been scanned. - `\Datetime createdAt` RFC 3339. - `?CreatedBy createdBy` Who created the Plugin; null when no creator is recorded. - `?string description` The served version's description. - `?string displayName` The served version's display name. - `string latestVersionID` The newest version. - `?string manifestVersion` The served version's manifest `version`, normalized for display, or `null` (the Plugin Version's `manifest_version` says how and when). - `string marketplaceID` The ID of the plugin marketplace the Plugin lives in. - `string name` 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. - `?OrganizationInstallationPreference organizationInstallationPreference` 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. - `?bool organizationInstallationPreferenceInherited` 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 owner` Who owns the Plugin: the organization, or the member whose personal plugin marketplace it lives in. - `?Reach reach` 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`. - `string servedVersionID` The version claude.ai serves to members. - `bool servedVersionPinned` True once the served version has been pinned, through Update Plugin or in claude.ai. While false, a new version normally becomes the served version when it is stored. While the newest version is not the served version, as when a version saved in claude.ai is waiting for its content scan, `served_version_id` differs from `latest_version_id`. - `\Datetime updatedAt` RFC 3339. Moves on a served-version change (including pinning an unpinned Plugin to the version it already serves) and, normally, on a new version. A version saved in claude.ai that waits for its content scan moves it when it becomes the served version, and not necessarily when it is stored. A change to the Plugin's installation settings or shares does not move it. #### Example ```php beta->organization->plugins->update( 'plugin_id', servedVersionID: 'pluginver_01KaZmQpRsTuVwXyZ2b4c6d8', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaPlugin); ``` ##### 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_01WxYzAbCdEfGhJkMnPqRsTu" }, "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 `$client->beta->organization->plugins->list(?\Datetime createdAtGt, ?\Datetime createdAtGte, ?\Datetime createdAtLt, ?\Datetime createdAtLte, ?int limit, ?string marketplaceID, ?string organizationID, ?OwnerType ownerType, ?string ownerUserID, ?string page, ?list betas): PageCursor` **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 - `createdAtGt?: optional \Datetime` (query parameter) RFC 3339 timestamp bound; combine [gte], [gt], [lte], [lt]. - `createdAtGte?: optional \Datetime` (query parameter) RFC 3339 timestamp bound; combine [gte], [gt], [lte], [lt]. - `createdAtLt?: optional \Datetime` (query parameter) RFC 3339 timestamp bound; combine [gte], [gt], [lte], [lt]. - `createdAtLte?: optional \Datetime` (query parameter) RFC 3339 timestamp bound; combine [gte], [gt], [lte], [lt]. - `limit?: optional int` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `100`. default: 20 - `marketplaceID?: optional string` (query parameter) Only Plugins in this plugin marketplace (prefixed `marketplace_`). - `organizationID?: 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. - `ownerType?: optional OwnerType` (query parameter) `organization` for Plugins in the organization's plugin marketplaces, `user` for Plugins in members' personal plugin marketplaces. - `ownerUserID?: 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. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `class Plugin` - `"plugin" type` Always `plugin`. - `string id` The Plugin's ID. - `?list components` What the served version contains; null when not enumerated. - `?PluginContentScan contentScan` The served version's content scan; null when it has not been scanned. - `\Datetime createdAt` RFC 3339. - `?CreatedBy createdBy` Who created the Plugin; null when no creator is recorded. - `?string description` The served version's description. - `?string displayName` The served version's display name. - `string latestVersionID` The newest version. - `?string manifestVersion` The served version's manifest `version`, normalized for display, or `null` (the Plugin Version's `manifest_version` says how and when). - `string marketplaceID` The ID of the plugin marketplace the Plugin lives in. - `string name` 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. - `?OrganizationInstallationPreference organizationInstallationPreference` 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. - `?bool organizationInstallationPreferenceInherited` 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 owner` Who owns the Plugin: the organization, or the member whose personal plugin marketplace it lives in. - `?Reach reach` 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`. - `string servedVersionID` The version claude.ai serves to members. - `bool servedVersionPinned` True once the served version has been pinned, through Update Plugin or in claude.ai. While false, a new version normally becomes the served version when it is stored. While the newest version is not the served version, as when a version saved in claude.ai is waiting for its content scan, `served_version_id` differs from `latest_version_id`. - `\Datetime updatedAt` RFC 3339. Moves on a served-version change (including pinning an unpinned Plugin to the version it already serves) and, normally, on a new version. A version saved in claude.ai that waits for its content scan moves it when it becomes the served version, and not necessarily when it is stored. A change to the Plugin's installation settings or shares does not move it. #### Example ```php beta->organization->plugins->list( createdAtGt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtGte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtLt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtLte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), limit: 1, marketplaceID: 'marketplace_id', organizationID: 'organization_id', ownerType: 'organization', ownerUserID: 'owner_user_id', page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### 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_01WxYzAbCdEfGhJkMnPqRsTu" }, "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 `$client->beta->organization->plugins->delete(string pluginID, ?list betas): DeletedPlugin` **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 - `pluginID: string` (path parameter) ID of the Plugin (prefixed `plugin_`). - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `class DeletedPlugin` - `"plugin_deleted" type` Always `plugin_deleted`. - `string id` The deleted Plugin's ID. #### Example ```php beta->organization->plugins->delete( 'plugin_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24] ); var_dump($betaDeletedPlugin); ``` ##### Response (200) ```json { "id": "plugin_01JyHfbRkZvD1gW7oTqXc3Ne", "type": "plugin_deleted" } ``` ## Beta › Organization › Plugins › Versions ### Create Plugin Version `$client->beta->organization->plugins->versions->create(string pluginID, list files, ?string releaseNotes, ?list betas): BetaPluginVersion` **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=php#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 - `pluginID: string` (path parameter) ID of the Plugin (prefixed `plugin_`). - `files: list` 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`. - `releaseNotes?: optional string` Release notes stored with the version and shown in its version history in claude.ai; up to 5,000 characters. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `class BetaPluginVersion` - `"plugin_version" type` Always `plugin_version`. - `string id` The version's ID. - `?list components` What the version contains; null when not enumerated. - `?PluginContentScan contentScan` This version's content scan; null when it has not been scanned. - `\Datetime createdAt` RFC 3339. - `?CreatedBy createdBy` Who uploaded this version; null when not recorded. - `?string description` The manifest's description; null when it declares none. - `?string displayName` The manifest's display name; null when it declares none. - `?string manifestVersion` 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). - `string pluginID` The Plugin's ID. - `?Reach reach` How far the version reaches: `remote`, `privileged`, `contained`, or `null`, as defined on the Plugin's `reach`. - `?string releaseNotes` As supplied with the upload; null when none were supplied. #### Example ```php beta->organization->plugins->versions->create( 'plugin_id', files: [ FileParam::fromString('Example data', filename: uniqid('file-upload-', true)), ], releaseNotes: 'release_notes', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaPluginVersion); ``` ##### 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_01WxYzAbCdEfGhJkMnPqRsTu" }, "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 `$client->beta->organization->plugins->versions->list(string pluginID, ?int limit, ?string organizationID, ?string page, ?list betas): PageCursor` **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 - `pluginID: string` (path parameter) ID of the Plugin (prefixed `plugin_`). - `limit?: optional int` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. default: 20 - `organizationID?: 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. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `class BetaPluginVersion` - `"plugin_version" type` Always `plugin_version`. - `string id` The version's ID. - `?list components` What the version contains; null when not enumerated. - `?PluginContentScan contentScan` This version's content scan; null when it has not been scanned. - `\Datetime createdAt` RFC 3339. - `?CreatedBy createdBy` Who uploaded this version; null when not recorded. - `?string description` The manifest's description; null when it declares none. - `?string displayName` The manifest's display name; null when it declares none. - `?string manifestVersion` 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). - `string pluginID` The Plugin's ID. - `?Reach reach` How far the version reaches: `remote`, `privileged`, `contained`, or `null`, as defined on the Plugin's `reach`. - `?string releaseNotes` As supplied with the upload; null when none were supplied. #### Example ```php beta->organization->plugins->versions->list( 'plugin_id', limit: 1, organizationID: 'organization_id', page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### 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_01WxYzAbCdEfGhJkMnPqRsTu" }, "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 `$client->beta->organization->plugins->versions->retrieve(string version, string pluginID, ?string organizationID, ?list betas): BetaPluginVersion` **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 - `pluginID: 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. - `organizationID?: 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. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `class BetaPluginVersion` - `"plugin_version" type` Always `plugin_version`. - `string id` The version's ID. - `?list components` What the version contains; null when not enumerated. - `?PluginContentScan contentScan` This version's content scan; null when it has not been scanned. - `\Datetime createdAt` RFC 3339. - `?CreatedBy createdBy` Who uploaded this version; null when not recorded. - `?string description` The manifest's description; null when it declares none. - `?string displayName` The manifest's display name; null when it declares none. - `?string manifestVersion` 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). - `string pluginID` The Plugin's ID. - `?Reach reach` How far the version reaches: `remote`, `privileged`, `contained`, or `null`, as defined on the Plugin's `reach`. - `?string releaseNotes` As supplied with the upload; null when none were supplied. #### Example ```php beta->organization->plugins->versions->retrieve( 'version', pluginID: 'plugin_id', organizationID: 'organization_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaPluginVersion); ``` ##### 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_01WxYzAbCdEfGhJkMnPqRsTu" }, "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 `$client->beta->organization->plugins->versions->download(string version, string pluginID, ?string organizationID, ?list betas): 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 - `pluginID: 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. - `organizationID?: 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. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `mixed` #### Example ```php beta->organization->plugins->versions->download( 'version', pluginID: 'plugin_id', organizationID: 'organization_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($response); ``` ## Beta › Organization › Plugins › Installation Settings ### List Plugin Installation Settings `$client->beta->organization->plugins->installationSettings->list(string pluginID, ?int limit, ?string organizationID, ?string page, ?TargetType targetType, ?list betas): PageCursor` **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 - `pluginID: string` (path parameter) ID of the Plugin (prefixed `plugin_`). - `limit?: optional int` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `100`. default: 20 - `organizationID?: 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. - `targetType?: optional TargetType` (query parameter) Only settings for this kind of target: `organization` (the organization-wide setting) or `rbac_group` (an RBAC Group's). - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `class BetaPluginInstallationSetting` - `"plugin_installation_setting" type` Always `plugin_installation_setting`. - `\Datetime createdAt` When the target was first given a setting for this Plugin. - `InstallationPreference installationPreference` 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. - `string pluginID` The Plugin's ID. - `Target target` 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. - `\Datetime updatedAt` When its setting last changed. #### Example ```php beta->organization->plugins->installationSettings->list( 'plugin_id', limit: 1, organizationID: 'organization_id', page: 'page', targetType: 'organization', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### 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 `$client->beta->organization->plugins->installationSettings->set(string target, string pluginID, InstallationPreference installationPreference, ?list betas): BetaPluginInstallationSetting` **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 - `pluginID: 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. - `installationPreference: InstallationPreference` The installation setting the target is to hold for this Plugin: one of `required`, `auto_install`, `available`, `not_available`. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `class BetaPluginInstallationSetting` - `"plugin_installation_setting" type` Always `plugin_installation_setting`. - `\Datetime createdAt` When the target was first given a setting for this Plugin. - `InstallationPreference installationPreference` 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. - `string pluginID` The Plugin's ID. - `Target target` 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. - `\Datetime updatedAt` When its setting last changed. #### Example ```php beta ->organization ->plugins ->installationSettings ->set( 'target', pluginID: 'plugin_id', installationPreference: 'required', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaPluginInstallationSetting); ``` ##### 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 `$client->beta->organization->plugins->installationSettings->remove(string target, string pluginID, ?list betas): BetaDeletedPluginInstallationSetting` **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 - `pluginID: 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. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `class BetaDeletedPluginInstallationSetting` - `"plugin_installation_setting_deleted" type` Always `plugin_installation_setting_deleted`. - `string pluginID` The Plugin's ID. - `Target target` Whose setting was removed. #### Example ```php beta ->organization ->plugins ->installationSettings ->remove( 'target', pluginID: 'plugin_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaDeletedPluginInstallationSetting); ``` ##### 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 `$client->beta->organization->plugins->shares->list(string pluginID, ?int limit, ?string organizationID, ?string page, ?TargetType targetType, ?list betas): PageCursor` **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 - `pluginID: string` (path parameter) ID of the Plugin (prefixed `plugin_`). - `limit?: optional int` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `100`. default: 20 - `organizationID?: 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. - `targetType?: optional TargetType` (query parameter) Only shares with this kind of target: `organization` (every member), `rbac_group` (one RBAC Group), or `organization_member` (one member). - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `class BetaPluginShare` - `"plugin_share" type` Always `plugin_share`. - `\Datetime grantedAt` 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. - `string pluginID` The Plugin's ID. - `Target target` Who the Plugin is shared with: `organization` (every member), `rbac_group` (one RBAC Group), or `organization_member` (one member). #### Example ```php beta->organization->plugins->shares->list( 'plugin_id', limit: 1, organizationID: 'organization_id', page: 'page', targetType: 'organization', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### 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 `$client->beta->organization->pluginMarketplaces->list(?int limit, ?string organizationID, ?OwnerType ownerType, ?string page, ?Source source, ?list betas): PageCursor` **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 int` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. default: 20 - `organizationID?: 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. - `ownerType?: optional OwnerType` (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. - `source?: optional Source` (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. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `class PluginMarketplace` - `"plugin_marketplace" type` Always `plugin_marketplace`. - `string id` The plugin marketplace's ID, prefixed `marketplace_`. - `\Datetime createdAt` RFC 3339. - `?DefaultInstallationPreference defaultInstallationPreference` 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. - `?\Datetime lastSyncEndedAt` 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. - `?string lastSyncReadSha` 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. - `string name` Fixed for the plugin marketplace's lifetime. - `Owner owner` The organization, or the member whose personal plugin marketplace it is. - `Source source` 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. - `?SyncStatus syncStatus` 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. #### Example ```php beta->organization->pluginMarketplaces->list( limit: 1, organizationID: 'organization_id', ownerType: 'organization', page: 'page', source: 'directory', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### 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 `$client->beta->organization->pluginMarketplaces->retrieve(string marketplaceID, ?string organizationID, ?list betas): PluginMarketplace` **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 - `marketplaceID: string` (path parameter) ID of the plugin marketplace (prefixed `marketplace_`). - `organizationID?: 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. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `class PluginMarketplace` - `"plugin_marketplace" type` Always `plugin_marketplace`. - `string id` The plugin marketplace's ID, prefixed `marketplace_`. - `\Datetime createdAt` RFC 3339. - `?DefaultInstallationPreference defaultInstallationPreference` 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. - `?\Datetime lastSyncEndedAt` 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. - `?string lastSyncReadSha` 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. - `string name` Fixed for the plugin marketplace's lifetime. - `Owner owner` The organization, or the member whose personal plugin marketplace it is. - `Source source` 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. - `?SyncStatus syncStatus` 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. #### Example ```php beta ->organization ->pluginMarketplaces ->retrieve( 'marketplace_id', organizationID: 'organization_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaPluginMarketplace); ``` ##### 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 `$client->beta->organization->pluginMarketplaces->update(string marketplaceID, DefaultInstallationPreference defaultInstallationPreference, ?list betas): PluginMarketplace` **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 - `marketplaceID: string` (path parameter) ID of the plugin marketplace (prefixed `marketplace_`). - `defaultInstallationPreference: DefaultInstallationPreference` 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. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `class PluginMarketplace` - `"plugin_marketplace" type` Always `plugin_marketplace`. - `string id` The plugin marketplace's ID, prefixed `marketplace_`. - `\Datetime createdAt` RFC 3339. - `?DefaultInstallationPreference defaultInstallationPreference` 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. - `?\Datetime lastSyncEndedAt` 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. - `?string lastSyncReadSha` 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. - `string name` Fixed for the plugin marketplace's lifetime. - `Owner owner` The organization, or the member whose personal plugin marketplace it is. - `Source source` 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. - `?SyncStatus syncStatus` 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. #### Example ```php beta ->organization ->pluginMarketplaces ->update( 'marketplace_id', defaultInstallationPreference: 'available', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaPluginMarketplace); ``` ##### 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 `$client->beta->organization->pluginMarketplaces->validateRepository(string repositoryURL, ?string ref, ?list betas): PluginMarketplaceValidationReport` **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 or as needing a GitHub sign-in; 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=php#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 - `repositoryURL: 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. - `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. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `class PluginMarketplaceValidationReport` - `"plugin_marketplace_validation_report" type` Always `plugin_marketplace_validation_report`. - `?string commitSha` 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. - `?string manifestError` 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. - `?string manifestErrorCode` A stable identifier for `manifest_error`; null when that is. - `list pluginErrors` One entry per plugin a synchronization would skip entirely, keyed by the plugin's name in marketplace.json. - `list pluginWarnings` One entry per plugin that would synchronize with some of its contents left out, keyed by the plugin's name in marketplace.json. - `?string ref` 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. - `int totalPluginCount` How many plugins marketplace.json declares; 0 when it could not be read. - `bool valid` True when marketplace.json is well-formed and no plugin would be skipped; warnings never make it false. #### Example ```php beta ->organization ->pluginMarketplaces ->validateRepository( repositoryURL: 'https://github.com/example-org/example-marketplace', ref: 'main', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaPluginMarketplaceValidationReport); ``` ##### 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 `$client->beta->organization->pluginMarketplaces->validateArchive(FileParam | string archive, ?list betas): PluginMarketplaceValidationReport` **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 or as needing a GitHub sign-in; 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=php#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: FileParam | 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. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `class PluginMarketplaceValidationReport` - `"plugin_marketplace_validation_report" type` Always `plugin_marketplace_validation_report`. - `?string commitSha` 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. - `?string manifestError` 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. - `?string manifestErrorCode` A stable identifier for `manifest_error`; null when that is. - `list pluginErrors` One entry per plugin a synchronization would skip entirely, keyed by the plugin's name in marketplace.json. - `list pluginWarnings` One entry per plugin that would synchronize with some of its contents left out, keyed by the plugin's name in marketplace.json. - `?string ref` 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. - `int totalPluginCount` How many plugins marketplace.json declares; 0 when it could not be read. - `bool valid` True when marketplace.json is well-formed and no plugin would be skipped; warnings never make it false. #### Example ```php beta ->organization ->pluginMarketplaces ->validateArchive( archive: FileParam::fromString('Example data', filename: uniqid('file-upload-', true)), betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaPluginMarketplaceValidationReport); ``` ##### 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 `$client->beta->organization->telemetryDestinations->create(string endpointURL, TelemetryDestinationWorkspacesParams workspaces, ?string displayName, ?array headers, ?TelemetryDestinationTracesParams traces, ?list betas): TelemetryDestination` **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=php#add-a-destination) to learn more about adding a destination. #### Parameters - `endpointURL: 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`. - `workspaces: TelemetryDestinationWorkspacesParams` Which of the organization's workspaces the destination covers. - `displayName?: optional string` Human-readable name for the destination. Optional. 1 to 255 characters. - `headers?: optional array` Request headers that the API sends with every delivery, typically your collector's authentication header (for example `authorization`). The API never returns the values. 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 TelemetryDestinationTracesParams` The settings for the traces that the destination receives. If you leave it out, every setting takes its default. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `telemetry-destinations-2026-08-11` in this header. #### Returns - `class TelemetryDestination` - `"telemetry_destination" type` - `string id` The unique ID of the destination (`tdst_...`). - `\Datetime createdAt` Time the destination was created. - `TelemetryDestinationDeliveryHealth deliveryHealth` The most recent delivery results for this destination. - `?string displayName` Human-readable name for the destination. Null when none was set. - `string endpointURL` 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. - `list headerNames` Names of the registered request headers. Header values are write-only and are never returned. - `TelemetryDestinationState state` Whether the destination receives deliveries. - `TelemetryDestinationTraces traces` The destination's settings for the traces it receives. - `\Datetime updatedAt` 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. - `TelemetryDestinationWorkspaces workspaces` Which of the organization's workspaces the destination covers. #### Example ```php beta ->organization ->telemetryDestinations ->create( endpointURL: 'x', workspaces: ['type' => 'all'], displayName: 'display_name', headers: ['foo' => 'string'], traces: [ 'contentMode' => TelemetryDestinationContentMode::METADATA_ONLY, 'enabled' => true, 'endpointURL' => 'endpoint_url', 'maxContentBytes' => 0, ], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaTelemetryDestination); ``` ##### 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 `$client->beta->organization->telemetryDestinations->list(?int limit, ?string page, ?list workspaceIDs, ?list betas): PageCursor` **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=php#set-up-api-tracing) to learn more about destinations. #### Parameters - `limit?: optional int` (query parameter) Number of destinations to return per page, between 1 and 1,000. Defaults to 20. - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. Leave it out to get the first page. - `workspaceIDs?: optional list` (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`. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `telemetry-destinations-2026-08-11` in this header. #### Returns - `class TelemetryDestination` - `"telemetry_destination" type` - `string id` The unique ID of the destination (`tdst_...`). - `\Datetime createdAt` Time the destination was created. - `TelemetryDestinationDeliveryHealth deliveryHealth` The most recent delivery results for this destination. - `?string displayName` Human-readable name for the destination. Null when none was set. - `string endpointURL` 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. - `list headerNames` Names of the registered request headers. Header values are write-only and are never returned. - `TelemetryDestinationState state` Whether the destination receives deliveries. - `TelemetryDestinationTraces traces` The destination's settings for the traces it receives. - `\Datetime updatedAt` 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. - `TelemetryDestinationWorkspaces workspaces` Which of the organization's workspaces the destination covers. #### Example ```php beta->organization->telemetryDestinations->list( limit: 0, page: 'page', workspaceIDs: ['string'], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### 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 `$client->beta->organization->telemetryDestinations->retrieve(string destinationID, ?list betas): TelemetryDestination` **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=php#delivery-and-health) to learn how the API delivers spans and when it disables a destination. #### Parameters - `destinationID: string` (path parameter) ID of the destination (`tdst_...`). - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `telemetry-destinations-2026-08-11` in this header. #### Returns - `class TelemetryDestination` - `"telemetry_destination" type` - `string id` The unique ID of the destination (`tdst_...`). - `\Datetime createdAt` Time the destination was created. - `TelemetryDestinationDeliveryHealth deliveryHealth` The most recent delivery results for this destination. - `?string displayName` Human-readable name for the destination. Null when none was set. - `string endpointURL` 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. - `list headerNames` Names of the registered request headers. Header values are write-only and are never returned. - `TelemetryDestinationState state` Whether the destination receives deliveries. - `TelemetryDestinationTraces traces` The destination's settings for the traces it receives. - `\Datetime updatedAt` 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. - `TelemetryDestinationWorkspaces workspaces` Which of the organization's workspaces the destination covers. #### Example ```php beta ->organization ->telemetryDestinations ->retrieve( 'destination_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24] ); var_dump($betaTelemetryDestination); ``` ##### 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 `$client->beta->organization->telemetryDestinations->update(string destinationID, ?string displayName, ?string endpointURL, ?array headers, ?TelemetryDestinationStateParams state, ?TelemetryDestinationTracesParams traces, ?TelemetryDestinationWorkspacesParams workspaces, ?list betas): TelemetryDestination` **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=php#delivery-and-health) to learn more about changing a destination. #### Parameters - `destinationID: string` (path parameter) ID of the destination (`tdst_...`). - `displayName?: optional string` New human-readable name, 1 to 255 characters. Null clears it. - `endpointURL?: 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. - `headers?: optional array` 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 TelemetryDestinationStateParams` Whether the destination receives deliveries after the update. The field can't be `null`. - `traces?: optional TelemetryDestinationTracesParams` The traces settings to change. Omitted settings keep their stored values. `null` sets every traces setting to its create default. - `workspaces?: optional TelemetryDestinationWorkspacesParams` 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. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `telemetry-destinations-2026-08-11` in this header. #### Returns - `class TelemetryDestination` - `"telemetry_destination" type` - `string id` The unique ID of the destination (`tdst_...`). - `\Datetime createdAt` Time the destination was created. - `TelemetryDestinationDeliveryHealth deliveryHealth` The most recent delivery results for this destination. - `?string displayName` Human-readable name for the destination. Null when none was set. - `string endpointURL` 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. - `list headerNames` Names of the registered request headers. Header values are write-only and are never returned. - `TelemetryDestinationState state` Whether the destination receives deliveries. - `TelemetryDestinationTraces traces` The destination's settings for the traces it receives. - `\Datetime updatedAt` 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. - `TelemetryDestinationWorkspaces workspaces` Which of the organization's workspaces the destination covers. #### Example ```php beta ->organization ->telemetryDestinations ->update( 'destination_id', displayName: 'display_name', endpointURL: 'endpoint_url', headers: ['foo' => 'string'], state: ['type' => 'enabled'], traces: [ 'contentMode' => TelemetryDestinationContentMode::METADATA_ONLY, 'enabled' => true, 'endpointURL' => 'endpoint_url', 'maxContentBytes' => 0, ], workspaces: ['type' => 'all'], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaTelemetryDestination); ``` ##### 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 `$client->beta->organization->telemetryDestinations->delete(string destinationID, ?list betas): DeletedTelemetryDestination` **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=php#delivery-and-health) to learn more about managing a destination. #### Parameters - `destinationID: string` (path parameter) ID of the destination (`tdst_...`). - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `telemetry-destinations-2026-08-11` in this header. #### Returns - `class DeletedTelemetryDestination` - `"telemetry_destination_deleted" type` - `string id` ID of the deleted destination (`tdst_...`). #### Example ```php beta ->organization ->telemetryDestinations ->delete( 'destination_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24] ); var_dump($betaDeletedTelemetryDestination); ``` ##### Response (200) ```json { "id": "id", "type": "telemetry_destination_deleted" } ``` ### Test a Telemetry Destination `$client->beta->organization->telemetryDestinations->test(string destinationID, ?list betas): TelemetryDestinationTestResponse` **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 - `destinationID: string` (path parameter) ID of the destination to test (starts with `tdst_`). - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `telemetry-destinations-2026-08-11` in this header. #### Returns - `class TelemetryDestinationTestResponse` - `"telemetry_destination_test" type` - `TelemetryDestinationTestResult result` How the test went: `success` when the destination answered with a 2xx status, else `failure` with the reason. #### Example ```php beta ->organization ->telemetryDestinations ->test('destination_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24]); var_dump($betaTelemetryDestinationTestResponse); ``` ##### Response (200) ```json { "result": { "type": "success" }, "type": "telemetry_destination_test" } ``` ## Beta › Organization › Telemetry Destinations › Workspaces ### List Telemetry Destination Workspaces `$client->beta->organization->telemetryDestinations->workspaces->list(string destinationID, ?int limit, ?string page, ?list betas): PageCursor` **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=php#choose-workspaces-for-a-destination) to learn more about choosing the workspaces of a destination. #### Parameters - `destinationID: string` (path parameter) ID of the destination (`tdst_...`). - `limit?: optional int` (query parameter) Number of entries to return per page, between 1 and 1,000. Defaults to 20. - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. Leave it out to get the first page. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `telemetry-destinations-2026-08-11` in this header. #### Returns - `class BetaTelemetryDestinationWorkspace` - `"telemetry_destination_workspace" type` - `\Datetime createdAt` Time the workspace was added to the list. - `string telemetryDestinationID` ID of the telemetry destination (`tdst_...`). - `string workspaceID` ID of the workspace (`wrkspc_...`). #### Example ```php beta->organization->telemetryDestinations->workspaces->list( 'destination_id', limit: 0, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### 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 `$client->beta->organization->telemetryDestinations->workspaces->add(string workspaceID, string destinationID, ?list betas): BetaTelemetryDestinationWorkspace` **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=php#choose-workspaces-for-a-destination) to learn more about choosing the workspaces of a destination. #### Parameters - `destinationID: string` (path parameter) ID of the destination (`tdst_...`). - `workspaceID: string` (path parameter) ID of the workspace to add (`wrkspc_...`). - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `telemetry-destinations-2026-08-11` in this header. #### Returns - `class BetaTelemetryDestinationWorkspace` - `"telemetry_destination_workspace" type` - `\Datetime createdAt` Time the workspace was added to the list. - `string telemetryDestinationID` ID of the telemetry destination (`tdst_...`). - `string workspaceID` ID of the workspace (`wrkspc_...`). #### Example ```php beta ->organization ->telemetryDestinations ->workspaces ->add( 'workspace_id', destinationID: 'destination_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaTelemetryDestinationWorkspace); ``` ##### 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 `$client->beta->organization->telemetryDestinations->workspaces->remove(string workspaceID, string destinationID, ?list betas): BetaDeletedTelemetryDestinationWorkspace` **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=php#choose-workspaces-for-a-destination) to learn more about choosing the workspaces of a destination. #### Parameters - `destinationID: string` (path parameter) ID of the destination (`tdst_...`). - `workspaceID: string` (path parameter) ID of the workspace to remove (`wrkspc_...`). - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `telemetry-destinations-2026-08-11` in this header. #### Returns - `class BetaDeletedTelemetryDestinationWorkspace` - `"telemetry_destination_workspace_deleted" type` - `string telemetryDestinationID` ID of the telemetry destination (`tdst_...`). - `string workspaceID` ID of the workspace that was removed (`wrkspc_...`). #### Example ```php beta ->organization ->telemetryDestinations ->workspaces ->remove( 'workspace_id', destinationID: 'destination_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaDeletedTelemetryDestinationWorkspace); ``` ##### Response (200) ```json { "telemetry_destination_id": "telemetry_destination_id", "type": "telemetry_destination_workspace_deleted", "workspace_id": "workspace_id" } ``` ## Beta › Organization › Webhooks ### Create Organization Webhook Endpoint `$client->beta->organization->webhooks->create(list enabledEvents, string url, ?string description, ?string name, ?list betas): NewOrganizationWebhookEndpoint` **POST** `/v1/organizations/webhooks` Create an organization webhook endpoint. An organization webhook endpoint belongs to the organization rather than to one of its workspaces. An organization can have at most 32 organization webhook endpoints, enabled or disabled. The response includes the endpoint's signing secret. No read returns it, so store it when you receive it. Every request must include the beta header `anthropic-beta: webhooks-2026-10-07`. A request without it returns `404`, exactly as if this API did not exist. Anthropic turns organization webhook endpoints on for each organization; until yours is on, requests also return `404`. Organization webhook endpoints are in beta and are not available to organizations with HIPAA readiness enabled. #### Parameters - `enabledEvents: list` The event types to deliver to the endpoint. Must list at least one. - `url: string` The HTTPS URL that deliveries are sent to. - `description?: optional string` Notes about the endpoint. - `name?: optional string` A short label for the endpoint. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `webhooks-2026-10-07` in this header. #### Returns - `class NewOrganizationWebhookEndpoint` - `string id` ID of the webhook endpoint. - `\Datetime createdAt` When the endpoint was created, in RFC 3339 format. - `string description` Notes about the endpoint. An empty string when none were given. - `string disabledReason` Why Anthropic disabled the endpoint automatically. An empty string when the endpoint is enabled, or when you disabled it. - `list enabledEvents` The event types delivered to the endpoint. - `string name` A short label for the endpoint. An empty string when none was given. - `string signingSecret` The secret Anthropic signs deliveries to the endpoint with (prefix `whsec_`). No other response returns it, so store it now. To replace it, regenerate the signing secret. - `OrganizationWebhookEndpointState state` Whether deliveries are sent to the endpoint. - `\Datetime updatedAt` When the endpoint was last changed, in RFC 3339 format. - `string url` The HTTPS URL that deliveries are sent to. #### Example ```php beta ->organization ->webhooks ->create( enabledEvents: ['user_profile.enforcement_action_opened'], url: 'x', description: 'description', name: 'name', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaNewOrganizationWebhookEndpoint); ``` ##### Response (200) ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "description": "description", "disabled_reason": "disabled_reason", "enabled_events": [ "user_profile.enforcement_action_opened" ], "name": "name", "signing_secret": "signing_secret", "state": "disabled", "updated_at": "2019-12-27T18:11:19.117Z", "url": "url" } ``` ### List Organization Webhook Endpoints `$client->beta->organization->webhooks->list(?string afterID, ?string beforeID, ?int limit, ?Order order, ?list betas): Page` **GET** `/v1/organizations/webhooks` List the organization's webhook endpoints. An organization webhook endpoint belongs to the organization rather than to one of its workspaces. The list does not include webhook endpoints that belong to a workspace. Every request must include the beta header `anthropic-beta: webhooks-2026-10-07`. A request without it returns `404`, exactly as if this API did not exist. Anthropic turns organization webhook endpoints on for each organization; until yours is on, requests also return `404`. Organization webhook endpoints are in beta and are not available to organizations with HIPAA readiness enabled. #### Parameters - `afterID?: 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. - `beforeID?: optional string` (query parameter) ID of a webhook endpoint to use as a cursor. Returns the first `limit` endpoints that come before it in list order, not the `limit` endpoints just before it. - `limit?: optional int` (query parameter) Number of items to return per page, up to `100`. The default, `0`, means `20`. default: 0 - `order?: optional Order` (query parameter) Sort order by `created_at`. Defaults to `desc`, newest first. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `webhooks-2026-10-07` in this header. #### Returns - `class OrganizationWebhookEndpoint` - `string id` ID of the webhook endpoint. - `\Datetime createdAt` When the endpoint was created, in RFC 3339 format. - `string description` Notes about the endpoint. An empty string when none were given. - `string disabledReason` Why Anthropic disabled the endpoint automatically. An empty string when the endpoint is enabled, or when you disabled it. - `list enabledEvents` The event types delivered to the endpoint. - `string name` A short label for the endpoint. An empty string when none was given. - `OrganizationWebhookEndpointState state` Whether deliveries are sent to the endpoint. - `\Datetime updatedAt` When the endpoint was last changed, in RFC 3339 format. - `string url` The HTTPS URL that deliveries are sent to. #### Example ```php beta->organization->webhooks->list( afterID: 'after_id', beforeID: 'before_id', limit: 0, order: 'asc', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "description": "description", "disabled_reason": "disabled_reason", "enabled_events": [ "user_profile.enforcement_action_opened" ], "name": "name", "state": "disabled", "updated_at": "2019-12-27T18:11:19.117Z", "url": "url" } ], "has_more": true, "first_id": "first_id", "last_id": "last_id" } ``` ### Get Organization Webhook Endpoint `$client->beta->organization->webhooks->retrieve(string webhookEndpointID, ?list betas): OrganizationWebhookEndpoint` **GET** `/v1/organizations/webhooks/{webhook_endpoint_id}` Retrieve an organization webhook endpoint by ID. Every request must include the beta header `anthropic-beta: webhooks-2026-10-07`. A request without it returns `404`, exactly as if this API did not exist. Anthropic turns organization webhook endpoints on for each organization; until yours is on, requests also return `404`. Organization webhook endpoints are in beta and are not available to organizations with HIPAA readiness enabled. #### Parameters - `webhookEndpointID: string` (path parameter) ID of the webhook endpoint. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `webhooks-2026-10-07` in this header. #### Returns - `class OrganizationWebhookEndpoint` - `string id` ID of the webhook endpoint. - `\Datetime createdAt` When the endpoint was created, in RFC 3339 format. - `string description` Notes about the endpoint. An empty string when none were given. - `string disabledReason` Why Anthropic disabled the endpoint automatically. An empty string when the endpoint is enabled, or when you disabled it. - `list enabledEvents` The event types delivered to the endpoint. - `string name` A short label for the endpoint. An empty string when none was given. - `OrganizationWebhookEndpointState state` Whether deliveries are sent to the endpoint. - `\Datetime updatedAt` When the endpoint was last changed, in RFC 3339 format. - `string url` The HTTPS URL that deliveries are sent to. #### Example ```php beta ->organization ->webhooks ->retrieve( 'webhook_endpoint_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24] ); var_dump($betaOrganizationWebhookEndpoint); ``` ##### Response (200) ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "description": "description", "disabled_reason": "disabled_reason", "enabled_events": [ "user_profile.enforcement_action_opened" ], "name": "name", "state": "disabled", "updated_at": "2019-12-27T18:11:19.117Z", "url": "url" } ``` ### Update Organization Webhook Endpoint `$client->beta->organization->webhooks->update(string webhookEndpointID, ?string description, ?list enabledEvents, ?string name, ?State state, ?string url, ?list betas): OrganizationWebhookEndpoint` **POST** `/v1/organizations/webhooks/{webhook_endpoint_id}` Update an organization webhook endpoint. Only the fields you send are changed. Every request must include the beta header `anthropic-beta: webhooks-2026-10-07`. A request without it returns `404`, exactly as if this API did not exist. Anthropic turns organization webhook endpoints on for each organization; until yours is on, requests also return `404`. Organization webhook endpoints are in beta and are not available to organizations with HIPAA readiness enabled. #### Parameters - `webhookEndpointID: string` (path parameter) ID of the webhook endpoint. - `description?: optional string` Notes about the endpoint. - `enabledEvents?: optional list` The event types to deliver to the endpoint. Replaces the whole set; an empty list leaves it unchanged. - `name?: optional string` A short label for the endpoint. - `state?: optional State` `disabled` stops deliveries. `enabled` resumes them and clears `disabled_reason`. Events that happen while the endpoint is disabled are never delivered. - `url?: optional string` The HTTPS URL that deliveries are sent to. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `webhooks-2026-10-07` in this header. #### Returns - `class OrganizationWebhookEndpoint` - `string id` ID of the webhook endpoint. - `\Datetime createdAt` When the endpoint was created, in RFC 3339 format. - `string description` Notes about the endpoint. An empty string when none were given. - `string disabledReason` Why Anthropic disabled the endpoint automatically. An empty string when the endpoint is enabled, or when you disabled it. - `list enabledEvents` The event types delivered to the endpoint. - `string name` A short label for the endpoint. An empty string when none was given. - `OrganizationWebhookEndpointState state` Whether deliveries are sent to the endpoint. - `\Datetime updatedAt` When the endpoint was last changed, in RFC 3339 format. - `string url` The HTTPS URL that deliveries are sent to. #### Example ```php beta ->organization ->webhooks ->update( 'webhook_endpoint_id', description: 'description', enabledEvents: ['user_profile.enforcement_action_opened'], name: 'name', state: 'disabled', url: 'x', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaOrganizationWebhookEndpoint); ``` ##### Response (200) ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "description": "description", "disabled_reason": "disabled_reason", "enabled_events": [ "user_profile.enforcement_action_opened" ], "name": "name", "state": "disabled", "updated_at": "2019-12-27T18:11:19.117Z", "url": "url" } ``` ### Delete Organization Webhook Endpoint `$client->beta->organization->webhooks->delete(string webhookEndpointID, ?list betas): DeletedOrganizationWebhookEndpoint` **DELETE** `/v1/organizations/webhooks/{webhook_endpoint_id}` Delete an organization webhook endpoint. Every request must include the beta header `anthropic-beta: webhooks-2026-10-07`. A request without it returns `404`, exactly as if this API did not exist. Anthropic turns organization webhook endpoints on for each organization; until yours is on, requests also return `404`. Organization webhook endpoints are in beta and are not available to organizations with HIPAA readiness enabled. #### Parameters - `webhookEndpointID: string` (path parameter) ID of the webhook endpoint. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `webhooks-2026-10-07` in this header. #### Returns - `class DeletedOrganizationWebhookEndpoint` - `"webhook_endpoint_deleted" type` Always `webhook_endpoint_deleted`. - `string id` ID of the deleted webhook endpoint. #### Example ```php beta ->organization ->webhooks ->delete( 'webhook_endpoint_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24] ); var_dump($betaDeletedOrganizationWebhookEndpoint); ``` ##### Response (200) ```json { "id": "id", "type": "webhook_endpoint_deleted" } ``` ### Regenerate Organization Webhook Endpoint Signing Secret `$client->beta->organization->webhooks->regenerateSigningSecret(string webhookEndpointID, ?list betas): OrganizationWebhookEndpointSigningSecret` **POST** `/v1/organizations/webhooks/{webhook_endpoint_id}/regenerate_signing_secret` Replace an organization webhook endpoint's signing secret. The old secret stops working immediately. The new secret is returned only in this response. Every request must include the beta header `anthropic-beta: webhooks-2026-10-07`. A request without it returns `404`, exactly as if this API did not exist. Anthropic turns organization webhook endpoints on for each organization; until yours is on, requests also return `404`. Organization webhook endpoints are in beta and are not available to organizations with HIPAA readiness enabled. #### Parameters - `webhookEndpointID: string` (path parameter) ID of the webhook endpoint. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `webhooks-2026-10-07` in this header. #### Returns - `class OrganizationWebhookEndpointSigningSecret` - `string signingSecret` The new signing secret. Deliveries are signed with it from now on, and no other response returns it. #### Example ```php beta ->organization ->webhooks ->regenerateSigningSecret( 'webhook_endpoint_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24] ); var_dump($betaOrganizationWebhookEndpointSigningSecret); ``` ##### Response (200) ```json { "signing_secret": "signing_secret" } ``` ## Beta › Organization › Claude Tag › Slack Channels ### Set Up Slack Channel `$client->beta->organization->claudeTag->slackChannels->create(ClaudeTagSlackChannelIdentifiers slack, ?ClaudeTagSettingsCreate settings, ?list betas): BetaClaudeTagSlackChannel` **POST** `/v1/organizations/claude_tag/slack_channels` Set a Slack channel up for Claude Tag and return it with its identifier. If the channel is already set up, whether in claude.ai, by Claude's first use in it or by an earlier request, the existing channel is returned, so the request can be repeated. `settings`, when sent, is applied as an update applies it. Before a channel is set up, Claude's Slack app confirms with Slack that the channel is in the workspace, is not archived and is visible to the app; a channel that fails the confirmation returns 404. Setting the channel up and applying `settings` are two steps: when the second is refused, the response is the refusal, the channel stays set up with every setting unset, and the error's `details.slack_channel_id` holds the channel's identifier. #### Parameters - `slack: ClaudeTagSlackChannelIdentifiers` Slack's own identifiers for the channel to set up. The organization must own the workspace. - `settings?: optional ClaudeTagSettingsCreate` Settings to store on the channel, applied as Update Slack Channel applies them. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `experimental-claude-tag-2026-10-21` in this header. #### Returns - `class BetaClaudeTagSlackChannel` - `"slack_channel" type` - `string id` The channel's identifier. Starts with `slch_`. It does not change for as long as the channel is set up, with one exception: a channel that is not configured can get a new one. A channel that is removed and set up again also has a new one. The old one keeps returning 404; look the channel up by its Slack identifiers for the new one. - `\Datetime createdAt` Time the channel was set up, by whichever route. It does not change for as long as `id` does not. - `ClaudeTagSettings settings` What the channel itself stores or, with `include_inherited`, what applies in it. `sources` says which. - `ClaudeTagSlackChannelIdentifiers slack` Slack's own identifiers for the channel. - `ClaudeTagSettingSources sources` For each setting, the settings level its value in `settings` comes from. - `\Datetime updatedAt` Time Claude Tag's record of the channel last changed. It moves on every change to a setting, and can also move when something no response holds changes, so a later value says to read the channel again, not that a setting changed. Attaching or detaching a Bundle does not by itself move it. #### Example ```php beta ->organization ->claudeTag ->slackChannels ->create( slack: ['channelID' => 'xx', 'workspaceID' => 'xx'], settings: [ 'enabled' => true, 'environmentID' => 'x', 'guestPolicy' => ['type' => 'allow'], 'instructions' => 'instructions', 'model' => 'x', ], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaClaudeTagSlackChannel); ``` ##### Response (200) ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "settings": { "enabled": true, "environment_id": "environment_id", "guest_policy": { "type": "allow" }, "instructions": "instructions", "model": "model" }, "slack": { "channel_id": "xx", "workspace_id": "xx" }, "sources": { "enabled": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "environment_id": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "guest_policy": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "instructions": [ { "slack_channel_id": "slack_channel_id", "type": "slack_channel" } ], "model": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" } }, "type": "slack_channel", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ### List Slack Channels `$client->beta->organization->claudeTag->slackChannels->list(string slackWorkspaceID, ?bool includeInherited, ?int limit, ?string page, ?string slackChannelID, ?list betas): PageCursor` **GET** `/v1/organizations/claude_tag/slack_channels` List the set-up Slack channels of one Slack workspace, newest first by `created_at`. A channel that is not set up is not listed: Slack holds the full list of a workspace's channels. Pass `slack_channel_id` as well to look one channel up by its Slack identifiers: `data` then holds that channel, or is empty when it is not set up, and `limit` and `page` are ignored. A workspace that the organization owns only through a Slack Enterprise Grid returns 404 until it is set up. With `include_inherited=true` each channel's `settings` holds what applies in it, and the request fails with 503 rather than resolve against a settings level that could not be read. A `page` cursor resumes only a request with the same `include_inherited`. #### Parameters - `slackWorkspaceID: string` (query parameter) The Slack workspace whose channels to list: Slack's identifier for it, as in the channel object's `slack.workspace_id`, not the workspace object's `id`. - `includeInherited?: optional bool` (query parameter) When `true`, `settings` holds what applies in each channel once the settings levels above it are taken into account, and every member of `sources` names the level a value comes from. When `false` or left out, `settings` holds what each channel itself stores. - `limit?: optional int` (query parameter) Number of items to return per page, between 1 and 100. Defaults to 20. - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. - `slackChannelID?: optional string` (query parameter) Slack's identifier for one channel of that workspace, as in the channel object's `slack.channel_id`. It is not the channel object's `id`. With it `data` holds that channel alone, or nothing when the channel is not set up. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `experimental-claude-tag-2026-10-21` in this header. #### Returns - `class BetaClaudeTagSlackChannel` - `"slack_channel" type` - `string id` The channel's identifier. Starts with `slch_`. It does not change for as long as the channel is set up, with one exception: a channel that is not configured can get a new one. A channel that is removed and set up again also has a new one. The old one keeps returning 404; look the channel up by its Slack identifiers for the new one. - `\Datetime createdAt` Time the channel was set up, by whichever route. It does not change for as long as `id` does not. - `ClaudeTagSettings settings` What the channel itself stores or, with `include_inherited`, what applies in it. `sources` says which. - `ClaudeTagSlackChannelIdentifiers slack` Slack's own identifiers for the channel. - `ClaudeTagSettingSources sources` For each setting, the settings level its value in `settings` comes from. - `\Datetime updatedAt` Time Claude Tag's record of the channel last changed. It moves on every change to a setting, and can also move when something no response holds changes, so a later value says to read the channel again, not that a setting changed. Attaching or detaching a Bundle does not by itself move it. #### Example ```php beta->organization->claudeTag->slackChannels->list( slackWorkspaceID: 'slack_workspace_id', includeInherited: true, limit: 0, page: 'page', slackChannelID: 'slack_channel_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "settings": { "enabled": true, "environment_id": "environment_id", "guest_policy": { "type": "allow" }, "instructions": "instructions", "model": "model" }, "slack": { "channel_id": "xx", "workspace_id": "xx" }, "sources": { "enabled": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "environment_id": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "guest_policy": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "instructions": [ { "slack_channel_id": "slack_channel_id", "type": "slack_channel" } ], "model": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" } }, "type": "slack_channel", "updated_at": "2019-12-27T18:11:19.117Z" } ], "next_page": "next_page" } ``` ### Get Slack Channel `$client->beta->organization->claudeTag->slackChannels->retrieve(string id, ?bool includeInherited, ?list betas): BetaClaudeTagSlackChannel` **GET** `/v1/organizations/claude_tag/slack_channels/{id}` Get one Slack channel and its settings. By default `settings` holds what the channel itself stores: a setting that is null there is not set on the channel and is inherited. With `include_inherited=true`, `settings` holds what applies in the channel once the settings levels above it are taken into account, and the request fails with 503 rather than resolve against a settings level that could not be read. Either way `sources` names the settings level each value comes from, so a caller tells the channel's own value from an inherited one by its source, not by whether it is null. #### Parameters - `id: string` (path parameter) The channel's identifier, starting with `slch_`. - `includeInherited?: optional bool` (query parameter) When `true`, `settings` holds what applies in the channel once the settings levels above it are taken into account, and every member of `sources` names the level a value comes from. When `false` or left out, `settings` holds what the channel itself stores. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `experimental-claude-tag-2026-10-21` in this header. #### Returns - `class BetaClaudeTagSlackChannel` - `"slack_channel" type` - `string id` The channel's identifier. Starts with `slch_`. It does not change for as long as the channel is set up, with one exception: a channel that is not configured can get a new one. A channel that is removed and set up again also has a new one. The old one keeps returning 404; look the channel up by its Slack identifiers for the new one. - `\Datetime createdAt` Time the channel was set up, by whichever route. It does not change for as long as `id` does not. - `ClaudeTagSettings settings` What the channel itself stores or, with `include_inherited`, what applies in it. `sources` says which. - `ClaudeTagSlackChannelIdentifiers slack` Slack's own identifiers for the channel. - `ClaudeTagSettingSources sources` For each setting, the settings level its value in `settings` comes from. - `\Datetime updatedAt` Time Claude Tag's record of the channel last changed. It moves on every change to a setting, and can also move when something no response holds changes, so a later value says to read the channel again, not that a setting changed. Attaching or detaching a Bundle does not by itself move it. #### Example ```php beta ->organization ->claudeTag ->slackChannels ->retrieve( 'slch_01SvpyRQK3nN6eH9uhRA7n1q', includeInherited: true, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaClaudeTagSlackChannel); ``` ##### Response (200) ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "settings": { "enabled": true, "environment_id": "environment_id", "guest_policy": { "type": "allow" }, "instructions": "instructions", "model": "model" }, "slack": { "channel_id": "xx", "workspace_id": "xx" }, "sources": { "enabled": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "environment_id": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "guest_policy": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "instructions": [ { "slack_channel_id": "slack_channel_id", "type": "slack_channel" } ], "model": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" } }, "type": "slack_channel", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ### Update Slack Channel `$client->beta->organization->claudeTag->slackChannels->update(string id, ClaudeTagSettingsUpdate settings, ?list betas): BetaClaudeTagSlackChannel` **POST** `/v1/organizations/claude_tag/slack_channels/{id}` Change the settings a Slack channel stores. The update is partial: a setting left out is unchanged, and a setting sent as null is cleared, so the channel inherits it. If any value is refused, no setting in the request is stored. A group direct message takes no settings and returns 400. #### Parameters - `id: string` (path parameter) The channel's identifier, starting with `slch_`. - `settings: ClaudeTagSettingsUpdate` The settings to change. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `experimental-claude-tag-2026-10-21` in this header. #### Returns - `class BetaClaudeTagSlackChannel` - `"slack_channel" type` - `string id` The channel's identifier. Starts with `slch_`. It does not change for as long as the channel is set up, with one exception: a channel that is not configured can get a new one. A channel that is removed and set up again also has a new one. The old one keeps returning 404; look the channel up by its Slack identifiers for the new one. - `\Datetime createdAt` Time the channel was set up, by whichever route. It does not change for as long as `id` does not. - `ClaudeTagSettings settings` What the channel itself stores or, with `include_inherited`, what applies in it. `sources` says which. - `ClaudeTagSlackChannelIdentifiers slack` Slack's own identifiers for the channel. - `ClaudeTagSettingSources sources` For each setting, the settings level its value in `settings` comes from. - `\Datetime updatedAt` Time Claude Tag's record of the channel last changed. It moves on every change to a setting, and can also move when something no response holds changes, so a later value says to read the channel again, not that a setting changed. Attaching or detaching a Bundle does not by itself move it. #### Example ```php beta ->organization ->claudeTag ->slackChannels ->update( 'slch_01SvpyRQK3nN6eH9uhRA7n1q', settings: [ 'enabled' => true, 'environmentID' => 'x', 'guestPolicy' => ['type' => 'allow'], 'instructions' => 'instructions', 'model' => 'x', ], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaClaudeTagSlackChannel); ``` ##### Response (200) ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "settings": { "enabled": true, "environment_id": "environment_id", "guest_policy": { "type": "allow" }, "instructions": "instructions", "model": "model" }, "slack": { "channel_id": "xx", "workspace_id": "xx" }, "sources": { "enabled": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "environment_id": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "guest_policy": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "instructions": [ { "slack_channel_id": "slack_channel_id", "type": "slack_channel" } ], "model": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" } }, "type": "slack_channel", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ### Remove Slack Channel `$client->beta->organization->claudeTag->slackChannels->delete(string id, ?list betas): BetaClaudeTagDeletedSlackChannel` **DELETE** `/v1/organizations/claude_tag/slack_channels/{id}` Remove a Slack channel from Claude Tag. This deletes the channel's stored settings and its Bundle Targets at once, and then, in the background, the channel's sessions and their transcripts, its memory, its routines and the artifacts published from it. None of it can be restored. The channel in Slack and its messages are unchanged. The request is refused with 400 and `error.details.error_code` `slack_channel_enabled` while `enabled` resolves to `true` for the channel, as a read with `include_inherited=true` returns it: set `enabled` to `false` on the channel first. This guards against removing a channel in use by mistake; it is not a way to keep Claude out, because the removal deletes the channel's own `enabled: false` with its other settings, after which the channel inherits again and Claude's next use of it can set it up anew with a new identifier. The identifier returns 404 as soon as the request returns, so a repeated removal returns 404. A group direct message returns 400, and so does a channel that holds configuration this API does not manage. #### Parameters - `id: string` (path parameter) The channel's identifier, starting with `slch_`. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `experimental-claude-tag-2026-10-21` in this header. #### Returns - `class BetaClaudeTagDeletedSlackChannel` - `"slack_channel_deleted" type` - `string id` The removed channel's identifier. #### Example ```php beta ->organization ->claudeTag ->slackChannels ->delete( 'slch_01SvpyRQK3nN6eH9uhRA7n1q', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaClaudeTagDeletedSlackChannel); ``` ##### Response (200) ```json { "id": "id", "type": "slack_channel_deleted" } ``` ## Beta › Organization › Claude Tag › Slack Workspaces ### List Slack Workspaces `$client->beta->organization->claudeTag->slackWorkspaces->list(?bool includeInherited, ?int limit, ?string page, ?string slackWorkspaceID, ?list betas): PageCursor` **GET** `/v1/organizations/claude_tag/slack_workspaces` List the set-up Slack workspaces the organization owns, newest first by `created_at`. Pass `slack_workspace_id` to look one workspace up by its Slack identifier: `data` then holds that workspace, or is empty when it is not set up. A workspace of a Slack Enterprise Grid the organization has connected returns 404 until it is set up. With `include_inherited=true` each workspace's `settings` holds what applies in it, and the request fails with 503 rather than resolve against a settings level that could not be read. A `page` cursor resumes only a request with the same `include_inherited`. #### Parameters - `includeInherited?: optional bool` (query parameter) When `true`, `settings` holds what applies in each workspace once the organization's Slack defaults are taken into account, and every member of `sources` names the level a value comes from. When `false` or left out, `settings` holds what each workspace itself stores. - `limit?: optional int` (query parameter) Number of items to return per page, between 1 and 100. Defaults to 20. - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. - `slackWorkspaceID?: optional string` (query parameter) Slack's identifier for one workspace, as in the workspace object's `slack.workspace_id`, not its `id`. With it `data` holds that workspace alone, or nothing when it is not set up. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `experimental-claude-tag-2026-10-21` in this header. #### Returns - `class BetaClaudeTagSlackWorkspace` - `"slack_workspace" type` - `string id` The workspace's identifier. Starts with `slws_`. It does not change for as long as the workspace is set up. A workspace that is removed and set up again has a new one, and the old one keeps returning 404; look the workspace up by its Slack identifier for the new one. - `\Datetime createdAt` Time the workspace was set up, by whichever route. It does not change for as long as `id` does not. - `ClaudeTagSettings settings` What the workspace itself stores or, with `include_inherited`, what applies in it. `sources` says which. - `ClaudeTagSlackWorkspaceIdentifiers slack` Slack's own identifier for the workspace. - `ClaudeTagSettingSources sources` For each setting, the settings level its value in `settings` comes from. - `\Datetime updatedAt` Time Claude Tag's record of the workspace last changed. It moves on every change to a setting, and can also move when something no response holds changes, so a later value says to read the workspace again, not that a setting changed. Attaching or detaching a Bundle does not by itself move it. #### Example ```php beta->organization->claudeTag->slackWorkspaces->list( includeInherited: true, limit: 0, page: 'page', slackWorkspaceID: 'slack_workspace_id', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "settings": { "enabled": true, "environment_id": "environment_id", "guest_policy": { "type": "allow" }, "instructions": "instructions", "model": "model" }, "slack": { "workspace_id": "workspace_id" }, "sources": { "enabled": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "environment_id": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "guest_policy": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "instructions": [ { "slack_channel_id": "slack_channel_id", "type": "slack_channel" } ], "model": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" } }, "type": "slack_workspace", "updated_at": "2019-12-27T18:11:19.117Z" } ], "next_page": "next_page" } ``` ### Get Slack Workspace `$client->beta->organization->claudeTag->slackWorkspaces->retrieve(string id, ?bool includeInherited, ?list betas): BetaClaudeTagSlackWorkspace` **GET** `/v1/organizations/claude_tag/slack_workspaces/{id}` Get one Slack workspace and its settings. By default `settings` holds what the workspace itself stores: a setting that is null there is not set on the workspace and is inherited. With `include_inherited=true`, `settings` holds what applies in the workspace once the organization's Slack defaults are taken into account, and the request fails with 503 rather than resolve against a settings level that could not be read. Either way `sources` names the settings level each value comes from. #### Parameters - `id: string` (path parameter) The workspace's identifier, starting with `slws_`. - `includeInherited?: optional bool` (query parameter) When `true`, `settings` holds what applies in the workspace once the organization's Slack defaults are taken into account, and every member of `sources` names the level a value comes from. When `false` or left out, `settings` holds what the workspace itself stores. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `experimental-claude-tag-2026-10-21` in this header. #### Returns - `class BetaClaudeTagSlackWorkspace` - `"slack_workspace" type` - `string id` The workspace's identifier. Starts with `slws_`. It does not change for as long as the workspace is set up. A workspace that is removed and set up again has a new one, and the old one keeps returning 404; look the workspace up by its Slack identifier for the new one. - `\Datetime createdAt` Time the workspace was set up, by whichever route. It does not change for as long as `id` does not. - `ClaudeTagSettings settings` What the workspace itself stores or, with `include_inherited`, what applies in it. `sources` says which. - `ClaudeTagSlackWorkspaceIdentifiers slack` Slack's own identifier for the workspace. - `ClaudeTagSettingSources sources` For each setting, the settings level its value in `settings` comes from. - `\Datetime updatedAt` Time Claude Tag's record of the workspace last changed. It moves on every change to a setting, and can also move when something no response holds changes, so a later value says to read the workspace again, not that a setting changed. Attaching or detaching a Bundle does not by itself move it. #### Example ```php beta ->organization ->claudeTag ->slackWorkspaces ->retrieve( 'slws_01Hq8TzW5mKc2YbX7vNd4RfJ', includeInherited: true, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaClaudeTagSlackWorkspace); ``` ##### Response (200) ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "settings": { "enabled": true, "environment_id": "environment_id", "guest_policy": { "type": "allow" }, "instructions": "instructions", "model": "model" }, "slack": { "workspace_id": "workspace_id" }, "sources": { "enabled": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "environment_id": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "guest_policy": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "instructions": [ { "slack_channel_id": "slack_channel_id", "type": "slack_channel" } ], "model": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" } }, "type": "slack_workspace", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ### Update Slack Workspace `$client->beta->organization->claudeTag->slackWorkspaces->update(string id, ClaudeTagSettingsUpdate settings, ?list betas): BetaClaudeTagSlackWorkspace` **POST** `/v1/organizations/claude_tag/slack_workspaces/{id}` Change the settings a Slack workspace stores. The update is partial: a setting left out is unchanged, and a setting sent as null is cleared, so the workspace inherits it. If any value is refused, no setting in the request is stored. #### Parameters - `id: string` (path parameter) The workspace's identifier, starting with `slws_`. - `settings: ClaudeTagSettingsUpdate` The settings to change. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `experimental-claude-tag-2026-10-21` in this header. #### Returns - `class BetaClaudeTagSlackWorkspace` - `"slack_workspace" type` - `string id` The workspace's identifier. Starts with `slws_`. It does not change for as long as the workspace is set up. A workspace that is removed and set up again has a new one, and the old one keeps returning 404; look the workspace up by its Slack identifier for the new one. - `\Datetime createdAt` Time the workspace was set up, by whichever route. It does not change for as long as `id` does not. - `ClaudeTagSettings settings` What the workspace itself stores or, with `include_inherited`, what applies in it. `sources` says which. - `ClaudeTagSlackWorkspaceIdentifiers slack` Slack's own identifier for the workspace. - `ClaudeTagSettingSources sources` For each setting, the settings level its value in `settings` comes from. - `\Datetime updatedAt` Time Claude Tag's record of the workspace last changed. It moves on every change to a setting, and can also move when something no response holds changes, so a later value says to read the workspace again, not that a setting changed. Attaching or detaching a Bundle does not by itself move it. #### Example ```php beta ->organization ->claudeTag ->slackWorkspaces ->update( 'slws_01Hq8TzW5mKc2YbX7vNd4RfJ', settings: [ 'enabled' => true, 'environmentID' => 'x', 'guestPolicy' => ['type' => 'allow'], 'instructions' => 'instructions', 'model' => 'x', ], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaClaudeTagSlackWorkspace); ``` ##### Response (200) ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "settings": { "enabled": true, "environment_id": "environment_id", "guest_policy": { "type": "allow" }, "instructions": "instructions", "model": "model" }, "slack": { "workspace_id": "workspace_id" }, "sources": { "enabled": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "environment_id": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "guest_policy": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" }, "instructions": [ { "slack_channel_id": "slack_channel_id", "type": "slack_channel" } ], "model": { "slack_channel_id": "slack_channel_id", "type": "slack_channel" } }, "type": "slack_workspace", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ## Beta › Organization › Claude Tag › Bundles ### List Bundles `$client->beta->organization->claudeTag->bundles->list(?int limit, ?string page, ?list betas): PageCursor` **GET** `/v1/organizations/claude_tag/bundles` List the organization's Bundles, newest first by `created_at`. A Bundle that Claude Tag manages for itself is not listed. #### Parameters - `limit?: optional int` (query parameter) Number of items to return per page, between 1 and 100. Defaults to 20. - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `experimental-claude-tag-2026-10-21` in this header. #### Returns - `class BetaClaudeTagBundle` - `"bundle" type` - `string id` The Bundle's identifier. Starts with `capp_`. - `\Datetime createdAt` Time the Bundle was created. - `?string description` What the Bundle is for. Null when it has none. Read-only. - `string displayName` The Bundle's name. Always set. Read-only. - `\Datetime updatedAt` Time of the last change to the Bundle. #### Example ```php beta->organization->claudeTag->bundles->list( limit: 0, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24] ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "description": "description", "display_name": "display_name", "type": "bundle", "updated_at": "2019-12-27T18:11:19.117Z" } ], "next_page": "next_page" } ``` ### Get Bundle `$client->beta->organization->claudeTag->bundles->retrieve(string bundleID, ?list betas): BetaClaudeTagBundle` **GET** `/v1/organizations/claude_tag/bundles/{bundle_id}` Get one Bundle. What the Bundle grants (connectors, repositories and credentials) is never returned. #### Parameters - `bundleID: string` (path parameter) The Bundle's identifier, starting with `capp_`. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `experimental-claude-tag-2026-10-21` in this header. #### Returns - `class BetaClaudeTagBundle` - `"bundle" type` - `string id` The Bundle's identifier. Starts with `capp_`. - `\Datetime createdAt` Time the Bundle was created. - `?string description` What the Bundle is for. Null when it has none. Read-only. - `string displayName` The Bundle's name. Always set. Read-only. - `\Datetime updatedAt` Time of the last change to the Bundle. #### Example ```php beta ->organization ->claudeTag ->bundles ->retrieve( 'capp_011CZkZjLP1cWxj5EtMmdgbq', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaClaudeTagBundle); ``` ##### Response (200) ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "description": "description", "display_name": "display_name", "type": "bundle", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ## Beta › Organization › Claude Tag › Bundles › Targets ### List Bundle Targets `$client->beta->organization->claudeTag->bundles->targets->list(string bundleID, ?int limit, ?string page, ?list betas): PageCursor` **GET** `/v1/organizations/claude_tag/bundles/{bundle_id}/targets` List the Slack channels and Slack workspaces a Bundle is attached to, newest first by `created_at`. Only channels and workspaces the organization owns are listed; a Bundle that is attached to anything else has no Bundle Target for it. #### Parameters - `bundleID: string` (path parameter) The Bundle's identifier, starting with `capp_`. - `limit?: optional int` (query parameter) Number of items to return per page, between 1 and 100. Defaults to 20. - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `experimental-claude-tag-2026-10-21` in this header. #### Returns - `class BetaClaudeTagBundleTarget` - `class BetaClaudeTagSlackChannelBundleTarget` - `"slack_channel" type` - `string id` The Bundle Target's identifier. Starts with `btgt_`. No two Bundle Targets have the same one, and the same Bundle and target always give the same one, also after a detach and a new attach. It is opaque. - `\Datetime createdAt` Time the Bundle was attached. - `string slackChannelID` The identifier of the Slack channel the Bundle is attached to, starting with `slch_`. It is the channel object's `id`, not Slack's `channel_id`. - `class BetaClaudeTagSlackWorkspaceBundleTarget` - `"slack_workspace" type` - `string id` The Bundle Target's identifier. Starts with `btgt_`. No two Bundle Targets have the same one, and the same Bundle and target always give the same one, also after a detach and a new attach. It is opaque. - `\Datetime createdAt` Time the Bundle was attached. - `string slackWorkspaceID` The identifier of the Slack workspace the Bundle is attached to, starting with `slws_`. #### Example ```php beta->organization->claudeTag->bundles->targets->list( 'capp_011CZkZjLP1cWxj5EtMmdgbq', limit: 0, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "slack_channel_id": "slack_channel_id", "type": "slack_channel" } ], "next_page": "next_page" } ``` ### Attach Bundle `$client->beta->organization->claudeTag->bundles->targets->create(string bundleID, BetaClaudeTagBundleTargetCreate target, ?list betas): BetaClaudeTagBundleTarget` **POST** `/v1/organizations/claude_tag/bundles/{bundle_id}/targets` Attach a Bundle to a Slack channel or a Slack workspace. A Bundle attached to a workspace can be used in the workspace and in every channel in it. Attaching a Bundle to a channel or workspace it is already attached to returns the existing Bundle Target. The channel or workspace must be set up: attaching never sets a channel up. A group direct message takes no Bundle and returns 400. #### Parameters - `bundleID: string` (path parameter) The Bundle's identifier, starting with `capp_`. - `target: BetaClaudeTagBundleTargetCreate` - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `experimental-claude-tag-2026-10-21` in this header. #### Returns - `class BetaClaudeTagBundleTarget` - `class BetaClaudeTagSlackChannelBundleTarget` - `"slack_channel" type` - `string id` The Bundle Target's identifier. Starts with `btgt_`. No two Bundle Targets have the same one, and the same Bundle and target always give the same one, also after a detach and a new attach. It is opaque. - `\Datetime createdAt` Time the Bundle was attached. - `string slackChannelID` The identifier of the Slack channel the Bundle is attached to, starting with `slch_`. It is the channel object's `id`, not Slack's `channel_id`. - `class BetaClaudeTagSlackWorkspaceBundleTarget` - `"slack_workspace" type` - `string id` The Bundle Target's identifier. Starts with `btgt_`. No two Bundle Targets have the same one, and the same Bundle and target always give the same one, also after a detach and a new attach. It is opaque. - `\Datetime createdAt` Time the Bundle was attached. - `string slackWorkspaceID` The identifier of the Slack workspace the Bundle is attached to, starting with `slws_`. #### Example ```php beta ->organization ->claudeTag ->bundles ->targets ->create( 'capp_011CZkZjLP1cWxj5EtMmdgbq', target: ['slackChannelID' => 'xxxxxxxx', 'type' => 'slack_channel'], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaClaudeTagBundleTarget); ``` ##### Response (200) ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "slack_channel_id": "slack_channel_id", "type": "slack_channel" } ``` ### Get Bundle Target `$client->beta->organization->claudeTag->bundles->targets->retrieve(string targetID, string bundleID, ?list betas): BetaClaudeTagBundleTarget` **GET** `/v1/organizations/claude_tag/bundles/{bundle_id}/targets/{target_id}` Get one Bundle Target. Returns 404 when `target_id` is the identifier of another Bundle's Bundle Target, or the Bundle Target was detached. #### Parameters - `bundleID: string` (path parameter) The Bundle's identifier, starting with `capp_`. - `targetID: string` (path parameter) The Bundle Target's identifier, starting with `btgt_`. Attach Bundle and List Bundle Targets return it. It is never the identifier of the channel or workspace. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `experimental-claude-tag-2026-10-21` in this header. #### Returns - `class BetaClaudeTagBundleTarget` - `class BetaClaudeTagSlackChannelBundleTarget` - `"slack_channel" type` - `string id` The Bundle Target's identifier. Starts with `btgt_`. No two Bundle Targets have the same one, and the same Bundle and target always give the same one, also after a detach and a new attach. It is opaque. - `\Datetime createdAt` Time the Bundle was attached. - `string slackChannelID` The identifier of the Slack channel the Bundle is attached to, starting with `slch_`. It is the channel object's `id`, not Slack's `channel_id`. - `class BetaClaudeTagSlackWorkspaceBundleTarget` - `"slack_workspace" type` - `string id` The Bundle Target's identifier. Starts with `btgt_`. No two Bundle Targets have the same one, and the same Bundle and target always give the same one, also after a detach and a new attach. It is opaque. - `\Datetime createdAt` Time the Bundle was attached. - `string slackWorkspaceID` The identifier of the Slack workspace the Bundle is attached to, starting with `slws_`. #### Example ```php beta ->organization ->claudeTag ->bundles ->targets ->retrieve( 'btgt_01SvpyRQK3nN6eH9uhRA7n1qHq8TzW5mKc2YbX7vNd4RfJ', bundleID: 'capp_011CZkZjLP1cWxj5EtMmdgbq', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaClaudeTagBundleTarget); ``` ##### Response (200) ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "slack_channel_id": "slack_channel_id", "type": "slack_channel" } ``` ### Detach Bundle `$client->beta->organization->claudeTag->bundles->targets->delete(string targetID, string bundleID, ?list betas): BetaClaudeTagDeletedBundleTarget` **DELETE** `/v1/organizations/claude_tag/bundles/{bundle_id}/targets/{target_id}` Detach a Bundle from a Slack channel or a Slack workspace. A repeated detach returns 404. #### Parameters - `bundleID: string` (path parameter) The Bundle's identifier, starting with `capp_`. - `targetID: string` (path parameter) The Bundle Target's identifier, starting with `btgt_`. Attach Bundle and List Bundle Targets return it. It is never the identifier of the channel or workspace. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `experimental-claude-tag-2026-10-21` in this header. #### Returns - `class BetaClaudeTagDeletedBundleTarget` - `"bundle_target_deleted" type` - `string id` The identifier the Bundle Target had. #### Example ```php beta ->organization ->claudeTag ->bundles ->targets ->delete( 'btgt_01SvpyRQK3nN6eH9uhRA7n1qHq8TzW5mKc2YbX7vNd4RfJ', bundleID: 'capp_011CZkZjLP1cWxj5EtMmdgbq', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($betaClaudeTagDeletedBundleTarget); ``` ##### Response (200) ```json { "id": "id", "type": "bundle_target_deleted" } ```