api-20261022T020713Z / page 3 of 7 / documentation capture

manage-claude/access-transparency Changed · +4 / -4 lines

from line 95

9595

9696Example JSON message:

9797

98```json

98```text wrap

9999{

100100 "id": "activity_013b013744txqZtFHLUaRqLr",

101101 "type": "anthropic_access",

from line 132

132132

133133Example JSON message:

134134

135```json

135```text wrap

136136{

137137 "id": "activity_01AbCdEfGhJkMnPqRsTuVwXy",

138138 "type": "cmek_preserve",

from line 211

211211 No. Automated processing does not generate `anthropic_access` events; you will see an `anthropic_access` event only if a human reviewer subsequently views the content. Separately, a `cmek_preserve` event is written when content is preserved, whether the preservation was initiated by a human reviewer or an automated safety pipeline.

212212 </Accordion>

213213

214 <Accordion title="We are a platform that serves Claude to our own end users. Can we enable Access Transparency?">

214 <Accordion title="Can a platform that serves Claude to its own end users enable Access Transparency?">

215215 Access Transparency is not available for platform deployments. Contact your Anthropic account representative to discuss your use case.

216216 </Accordion>

217217

218 <Accordion title="Will I see events for access that occurred before we enrolled, or for our older data?">

218 <Accordion title="Will I see events for access that occurred before my organization enrolled, or for its older data?">

219219 Access Transparency is not guaranteed to be retroactive. It covers human access to content written to the Claude API on or after your enrollment date. You might see events for access to content that was written before enrollment.

220220 </Accordion>

221221

manage-claude/access-transparency-log Changed · +5 / -5 lines

from line 148

148148 -H "anthropic-version: 2023-06-01"

149149```

150150

151```json

151```text

152152{

153153 "type": "transparency_log_keys",

154154 "origin": "axt.anthropic.com/25f6429a-3293-49bf-afed-cb312911554b",

from line 193

193193

194194A planned rotation is announced on this page at least 30 days before the new key signs its first checkpoint. During that notice period the new key is listed in `log_keys` and in this table with its switch date. Retired keys stay listed with their service dates. A key that does not appear in this table is not legitimate, whatever `GET /keys` returns. Treat a checkpoint that verifies under no listed key as a verification failure, and report it to your Anthropic account representative or [Anthropic support](https://support.claude.com).

195195

196[`axt-verify`](https://platform.claude.com/docs/en/manage-claude/access-transparency-log#verify-with-axt-verify) carries the current key in each release and never reads a key from the API. Each release carries exactly one key. On the switch date, Anthropic starts signing with the new key and publishes the `axt-verify` release that carries it. On the same date Anthropic re-issues every organization's latest checkpoint under the new key, even for a log that has not grown. Upgrade on the switch date. Running the old release after the switch fails with exit status `1`, and so does running the new release before it. Either failure clears once you run the matching release. A verifier you maintain yourself needs the new fingerprint, with its switch date, added before that date.

196`axt-verify` carries the current key in each release and never reads a key from the API (see [Verify with axt-verify](https://platform.claude.com/docs/en/manage-claude/access-transparency-log#verify-with-axt-verify)). Each release carries exactly one key. On the switch date, Anthropic starts signing with the new key and publishes the `axt-verify` release that carries it. On the same date Anthropic re-issues every organization's latest checkpoint under the new key, even for a log that has not grown. Upgrade on the switch date. Running the old release after the switch fails with exit status `1`, and so does running the new release before it. Either failure clears once you run the matching release. A verifier you maintain yourself needs the new fingerprint, with its switch date, added before that date.

197197

198198### Fetch an inclusion proof

199199

from line 212

212212 -H "anthropic-version: 2023-06-01"

213213```

214214

215```json

215```text

216216{

217217 "type": "transparency_log_inclusion_proof",

218218 "leaf_index": 41,

from line 258

258258 -H "anthropic-version: 2023-06-01"

259259```

260260

261```json

261```text

262262{

263263 "type": "transparency_log_consistency_proof",

264264 "hashes": [

from line 337

337337

338338For example, this access event as the Activity Feed serves it:

339339

340```json

340```text wrap

341341{

342342 "id": "activity_01GPXmAhizavrUuoXNn3tzeA",

343343 "type": "anthropic_access",

manage-claude/api-and-data-retention Changed · +5 / -5 lines

from line 77

7777

7878Your signed BAA is the official source of truth for which features are covered. The API also enforces these restrictions automatically. When a HIPAA-enabled organization sends a request that includes a non-eligible feature, the API returns a `400` error to prevent accidental use of features not covered by your BAA:

7979

80```json

80```text

8181{

8282 "type": "error",

8383 "error": {

from line 125

125125

126126Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, and Claude Mythos 5 are designated Covered Models (see the [Covered Models support article](https://support.claude.com/en/articles/15425695)) and require 30-day data retention; ZDR is therefore not available for any of them unless expressly authorized by Anthropic. On the Claude API, requests to Claude Fable 5 from an organization whose data retention configuration does not meet this requirement return a `400 invalid_request_error`:

127127

128```json

128```text

129129{

130130 "type": "error",

131131 "error": {

from line 170

172172| [Advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool) | `/v1/messages` with `advisor` tool | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Advisor model output is returned in the API response; nothing is stored server-side after the response. |

173| [Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) | `/v1/skills` `/v1/messages` with `skills` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Skill data retained per standard policy. See [Agent Skills data retention](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#data-retention). |

173| [Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) | `/v1/skills` `/v1/messages` with `skills` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Skill data retained according to standard policy. See [Agent Skills data retention](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#data-retention). |

175175| [Batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing) | `/v1/messages/batches` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | 29-day retention; async storage required. See [Batch processing data retention](https://platform.claude.com/docs/en/build-with-claude/batch-processing#data-retention). |

176176| [Browser use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool) | `/v1/messages` with `browser` toolset | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Client-side tool. Anthropic does not run browser actions or retain page content beyond standard API handling. Not covered under HIPAA readiness; requests that include the browser use tool are not blocked. See [Browser use data retention](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool#data-retention). |

from line 186

186186| [Fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode) | `/v1/messages` with `speed: "fast"` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Same Messages API endpoint with faster inference. ZDR applies regardless of speed setting. |

187187| [Files API](https://platform.claude.com/docs/en/build-with-claude/files) | `/v1/files` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Files retained until explicitly deleted or they reach their configured expiration. See [Files API file lifecycle](https://platform.claude.com/docs/en/build-with-claude/files#data-retention). |

189| [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) | `/v1/messages` with `mcp_servers` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Data retained per standard policy. See [MCP connector data retention](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#data-retention). |

189| [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) | `/v1/messages` with `mcp_servers` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Data retained according to standard policy. See [MCP connector data retention](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#data-retention). |

190190| [MCP tunnels](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview) | `/v1/tunnels` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Research preview. See [MCP tunnels security](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/security) for the data-flow boundary and subprocessor details. |

from line 201

203203| [Tool search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) | `/v1/messages` with `tool_search` tool | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Server-side tool run by Anthropic; the tool definitions in the request are searched in memory per call and nothing is stored after the response. |

204| [User profiles](https://platform.claude.com/docs/en/manage-claude/user-profiles) | `/v1/user_profiles` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Profiles are metadata about your end customers and don't contain prompts or outputs. The profile data you send is retained per standard policy until you delete the profile. Not covered under HIPAA readiness; requests to `/v1/user_profiles` are not blocked. See [What a profile contains and how Anthropic uses it](https://platform.claude.com/docs/en/manage-claude/user-profiles#what-a-profile-contains-and-how-anthropic-uses-it). |

204| [User profiles](https://platform.claude.com/docs/en/manage-claude/user-profiles) | `/v1/user_profiles` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Profiles are metadata about your end customers and don't contain prompts or outputs. The profile data you send is retained according to standard policy until you delete the profile. Not covered under HIPAA readiness; requests to `/v1/user_profiles` are not blocked. See [What a profile contains and how Anthropic uses it](https://platform.claude.com/docs/en/manage-claude/user-profiles#what-a-profile-contains-and-how-anthropic-uses-it). |

205205| [Web fetch](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool) | `/v1/messages` with `web_fetch` tool | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Fetched web content returned in the API response. [Dynamic filtering for web fetch](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool#dynamic-filtering) is not eligible for ZDR or HIPAA. Website publishers might retain request data (such as fetched URLs and request metadata) according to their own policies. |

206206| [Web search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool) | `/v1/messages` with `web_search` tool | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Real-time web search results returned in the API response. [Dynamic filtering for web search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool#dynamic-filtering) is not eligible for ZDR or HIPAA. |

207207

manage-claude/authentication Changed · +4 / -4 lines

from line 48

4848

4949The legacy `x-api-key: YOUR_API_KEY` header is still supported in place of `Authorization`.

5050

51Store API keys in a secrets manager, rotate them periodically, and disable or delete any key you suspect has leaked. On the [API keys page](https://platform.claude.com/settings/keys) in the Claude Console, **Disable** is reversible (the Admin API reports the key's `status` as `"inactive"`, and **Re-enable** returns it to `"active"`), while **Delete** is permanent: the key is archived and still appears in [List API Keys](https://platform.claude.com/docs/en/api/organization/api_keys/list) with `status: "archived"`. Expired keys can only be deleted. You can also set an [expiration](https://platform.claude.com/docs/en/manage-claude/authentication#key-expiration) when you create a key to limit how long a leaked credential stays usable.

51Store API keys in a secrets manager, rotate them periodically, and disable or delete any key you suspect has leaked. On the [API keys](https://platform.claude.com/settings/keys) page in the Claude Console, **Disable** is reversible (the Admin API reports the key's `status` as `"inactive"`, and **Re-enable** returns it to `"active"`), whereas **Delete** is permanent: the key is archived and still appears in [List API Keys](https://platform.claude.com/docs/en/api/organization/api_keys/list) with `status: "archived"`. Expired keys can only be deleted. You can also set an [expiration](https://platform.claude.com/docs/en/manage-claude/authentication#key-expiration) when you create a key to limit how long a leaked credential stays usable.

5252

5353<CodeGroup>

5454 ```bash cURL

from line 311

311311

312312If a request made with a key that isn't scoped to a workspace omits the header, the API returns a 400 `invalid_request_error`:

313313

314```json JSON

314```text JSON

315315{

316316 "type": "error",

317317 "error": {

from line 328

328328

329329### Key expiration

330330

331When you create an API key from the [API keys page](https://platform.claude.com/settings/keys) in the Claude Console, you choose an expiration: a preset (3 hours, 1 day, 7 days, or 30 days), a custom duration, or **Never** for keys you store in a secrets manager and rotate yourself. If your organization has a maximum expiration policy, the Console limits presets and custom durations to the policy maximum, and **Never** is unavailable. Existing keys keep their current behavior; expiration is set at creation time and cannot be changed afterward. The same expiration choice applies when you [create an Admin API key](https://platform.claude.com/docs/en/manage-claude/admin-api-keys) in the Claude Console.

331When you create an API key from the [API keys](https://platform.claude.com/settings/keys) page in the Claude Console, you choose an expiration: a preset (3 hours, 1 day, 7 days, or 30 days), a custom duration, or **Never** for keys you store in a secrets manager and rotate yourself. If your organization has a maximum expiration policy, the Console limits presets and custom durations to the policy maximum, and **Never** is unavailable. Existing keys keep their current behavior; expiration is set at creation time and cannot be changed afterward. The same expiration choice applies when you [create an Admin API key](https://platform.claude.com/docs/en/manage-claude/admin-api-keys) in the Claude Console.

332332

333333Anthropic emails the key's creator as the expiration approaches: 7 days before expiration for keys created with a lifetime of at least 14 days, and 1 day before for keys with a lifetime of at least 7 days. Keys with shorter lifetimes expire without a warning email.

334334

from line 348

348348

3493491. **Decide the key type.** Your own tooling should use a personal key. A shared or unattended workload should use a service account key.

3503502. **Create a service account** if necessary. You might have to ask an organization admin to create one on the [Service accounts](https://platform.claude.com/settings/service-accounts) page (`platform.claude.com/settings/service-accounts`) in the Claude Console and add it to the relevant workspace.

3513. **Create the new key.** Create it specifically for the integration's workspace unless multiple workspaces are needed.

3513. **Create the new key.** Create it specifically for the integration's workspace unless the integration needs multiple workspaces.

3523524. **Deploy the new key.** Replace the old key wherever the integration reads it, typically the `ANTHROPIC_API_KEY` environment variable or a secrets manager entry. For a key that isn't scoped to a workspace, also send the `anthropic-workspace-id` header as shown in [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace).

3533535. **Delete the old key.** Confirm that requests succeed, then delete the workspace key on the [API keys page](https://platform.claude.com/settings/keys) in the Claude Console.

354354

manage-claude/compliance-content-data Changed · +5 / -5 lines

from line 38

3838 --data-urlencode "limit=100"

3939```

4040

41```json Response

41```text Response

4242{

4343 "data": [

4444 {

from line 92

9292

9393The messages endpoint returns the chat's metadata plus a `chat_messages` array sorted by `created_at`. When `limit` is omitted, the full message set is returned in one response; pass `limit`, `after_id`, or `before_id` to page through very long chats. The endpoint also accepts `created_at.*` and `updated_at.*` range bounds (`gt`, `gte`, `lt`, `lte`) and an `order` parameter (`asc` or `desc`). See [Get chat messages](https://platform.claude.com/docs/en/api/compliance/apps/chats/messages/list) for the full parameter list. For user messages, `created_at` is when the message was sent; for assistant messages, it is when Claude finished generating the message. Each message carries its text content and, when present, any uploaded files (typically on user messages), any tool-generated files, and any artifacts the assistant produced or updated (typically on assistant messages):

9494

95```json Response

95```text Response

9696{

9797 "id": "claude_chat_01H5CWunD7RpVJ5bHa8RCkja",

9898 "name": "Product Requirements Discussion",

from line 232

232232 -H "anthropic-version: 2023-06-01"

233233```

234234

235```json Response

235```text Response wrap

236236{

237237 "data": [

238238 {

from line 289

289289 -H "anthropic-version: 2023-06-01"

290290```

291291

292```json Response

292```text Response wrap

293293{

294294 "id": "claude_chat_01H5CWunD7RpVJ5bHa8RCkja",

295295 "type": "claude_chat_deleted"

from line 302

302302

303303A project cannot be deleted while any chats remain attached to it. The API returns 409 with this body:

304304

305```json

305```text

306306{

307307 "error": {

308308 "type": "invalid_request_error",

manage-claude/compliance-errors Changed · +3 / -3 lines

from line 12

1212

1313The Compliance API returns errors in the standard [Anthropic error format](https://platform.claude.com/docs/en/api/errors): a non-2xx status code, a `request-id` response header, and a JSON body with an `error` object containing `type` and `message`. Include the `request-id` header value when you escalate to support.

1414

15```json

15```text

1616{

1717 "error": {

1818 "type": "permission_error",

from line 423

423423

424424A 429 response also carries a `retry-after` header with the number of seconds to wait before sending the next request. This value might include a small safety margin beyond `anthropic-ratelimit-requests-reset`; honor `retry-after`.

425425

426```http

426```text wrap

427427HTTP/1.1 429 Too Many Requests

428428date: Tue, 21 Apr 2026 14:38:02 GMT

429429retry-after: 25

from line 432

432432anthropic-ratelimit-requests-reset: 2026-04-21T14:38:25Z

433433```

434434

435```json

435```text

436436{

437437 "error": {

438438 "type": "rate_limit_error",

manage-claude/compliance-org-data Changed · +8 / -8 lines

from line 29

2929 -H "anthropic-version: 2023-06-01"

3030```

3131

32```json Response

32```text Response wrap

3333{

3434 "data": [

3535 {

from line 80

8080 --data-urlencode "limit=500"

8181```

8282

83```json Response

83```text Response wrap

8484{

8585 "data": [

8686 {

from line 115

115115 -H "anthropic-version: 2023-06-01"

116116```

117117

118```json Response

118```text Response wrap

119119{

120120 "data": [

121121 {

from line 145

145145 -H "anthropic-version: 2023-06-01"

146146```

147147

148```json Response

148```text Response

149149{

150150 "data": [

151151 {

from line 180

180180 -H "anthropic-version: 2023-06-01"

181181```

182182

183```json Response

183```text Response wrap

184184{

185185 "data": [

186186 {

from line 207

207207 -H "anthropic-version: 2023-06-01"

208208```

209209

210```json Response

210```text Response wrap

211211{

212212 "data": [

213213 {

from line 243

243243

244244The response is a list of typed setting rows, and which rows appear varies by organization: a setting the organization's administrators cannot change, because it is controlled by Anthropic policy or not available to the organization, is omitted from the list. Treat a missing row as "not controllable by this organization's administrators", not as "off". The following abridged example shows three of the rows a response can contain:

245245

246```json Response

246```text Response wrap

247247{

248248 "type": "effective_organization_settings",

249249 "organization_id": "91012d09-e48b-438e-a489-1bebfd8fa6f9",

from line 287

287287

288288Each row carries `name`, `type`, and `value`; the `type` field (`boolean`, `integer`, `string_list`, `provisioning_mode`, or `data_retention`) tells you the shape of `value`. The full list of setting names, and the `value` schema for each type, is in [Get effective organization settings](https://platform.claude.com/docs/en/api/compliance/organizations/settings/retrieve) in the API reference.

289289

290The `api_keys` array lists every Compliance Access Key configured for your parent organization, so the same list is returned regardless of which linked organization you query. Each entry carries the key's `type` (`compliance_api_key`), `id`, `name`, `scopes`, `is_active` flag, `created_at` and `expires_at` timestamps, and `created_by_id` (the ID of the user who created the key; might be `null`). The key's secret value is never returned. Deactivated keys are included with `is_active: false` so you can review keys that previously had access, and keys that carry only the retired `read:compliance_org_settings` scope remain in the list for audit and cleanup visibility even though that scope no longer grants access.

290The `api_keys` array lists every Compliance Access Key configured for your parent organization, so the same list is returned regardless of which linked organization you query. Each entry carries the key's `type` (`compliance_api_key`), `id`, `name`, `scopes`, `is_active` flag, `created_at` and `expires_at` timestamps, and `created_by_id` (the ID of the user who created the key, or `null`). The key's secret value is never returned. Deactivated keys are included with `is_active: false` so you can review keys that previously had access, and keys that carry only the retired `read:compliance_org_settings` scope remain in the list for audit and cleanup visibility even though that scope no longer grants access.

291291

292292The top-level `organization_id` is the organization's bare UUID: the same value as `uuid` in the organizations list, not the `org_`-prefixed form that `organization_id` carries on Activity Feed, chat, and project records (see the [organization identifier table](https://platform.claude.com/docs/en/manage-claude/compliance-org-data#list-organizations)).

293293

manage-claude/compliance-sessions Changed · +4 / -4 lines

from line 77

7777 --data-urlencode "limit=100"

7878```

7979

80```json Response

80```text Response wrap

8181{

8282 "data": [

8383 {

from line 164

164164 -H "anthropic-version: 2023-06-01"

165165```

166166

167```json Response

167```text Response

168168{

169169 "session": {

170170 "type": "compliance_local_session",

from line 316

316316 --data-urlencode "limit=100"

317317```

318318

319```json Response

319```text Response wrap

320320{

321321 "data": [

322322 {

from line 381

381381 -H "anthropic-version: 2023-06-01"

382382```

383383

384```json Response

384```text Response

385385{

386386 "session": {

387387 "id": "cse_01WpQrStUvXyZaBcDeFgHjK6",

manage-claude/data-residency Changed · +6 / -6 lines

from line 7

77Data residency controls let you manage where your data is processed and stored. Two independent settings govern this:

88

99* **Inference geo:** Controls where model inference runs, on a per-request basis. Set through the `inference_geo` API parameter or as a workspace default.

10* **Workspace geo:** Controls where data is stored at rest and where endpoint processing (such as image transcoding and code execution) occurs. Configured at the workspace level in the [Claude Console](https://platform.claude.com).

10* **Workspace geo:** Controls where data is stored at rest and where endpoint processing (such as image transcoding and code execution) occurs. Configured at the workspace level in the [Claude Console](https://platform.claude.com/).

1111

1212<Note>

1313 [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) supports geographic pinning at the agent level: `inference_geo` on an [agent's model configuration](https://platform.claude.com/docs/en/managed-agents/agent-setup#pin-the-inference-geo) pins the geography that serves model requests for sessions running that agent, with [per-session overrides](https://platform.claude.com/docs/en/managed-agents/sessions#pin-the-inference-geo-for-a-session) at session create. Agents without a pin follow the workspace's default inference geo on each request. Managed Agents also respects the Workspace geo configured in Console, and with [self-hosted sandboxes](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes), tool execution and the sandbox filesystem stay on infrastructure you control; the contents of attached [memory stores](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-memory) remain stored by Anthropic and are copied to your sandbox for the session.

from line 208

208208

209209The response `usage` object includes an `inference_geo` field indicating where inference ran:

210210

211```json Output

211```text Output wrap

212212{

213213 "usage": {

214214 "input_tokens": 25,

from line 239

239239

240240Workspace geo is set when you create a workspace and can't be changed afterward. Currently, `"us"` is the only available workspace geo.

241241

242To set workspace geo, create a new workspace in the [Console](https://platform.claude.com):

242To set workspace geo, create a new workspace in the [Console](https://platform.claude.com/):

243243

2441. In the Console, go to the [Workspaces](https://platform.claude.com/settings/workspaces) page (`platform.claude.com/settings/workspaces`).

2441. Go to [Workspaces in the Claude Console](https://platform.claude.com/settings/workspaces) (`platform.claude.com/settings/workspaces`).

2452452. Click **Create workspace** to open the [Create workspace](https://platform.claude.com/settings/workspaces/new) page (`platform.claude.com/settings/workspaces/new`) in the Console.

2462463. Enter a name, confirm the value in the **Workspace geo** field, and click **Create workspace**.

247247

from line 307

307307## Next steps

308308

309309<CardGroup>

310 <Card title="Pricing" icon="dollar-sign" href="https://platform.claude.com/docs/en/about-claude/pricing#data-residency-pricing">

310 <Card title="Data residency pricing" icon="dollar-sign" href="https://platform.claude.com/docs/en/about-claude/pricing#data-residency-pricing">

311311 View data residency pricing details.

312312 </Card>

313313

manage-claude/plugins-api Changed · +17 / -17 lines

from line 37

3737## Prerequisites

3838

3939* Your organization must be on a Claude Enterprise plan.

40* Your primary owner creates an Admin API key with the `read:plugins` scope, the `write:plugins` scope, or both in [claude.ai > Organization settings > API](https://claude.ai/admin-settings/api-access). See [Create an Admin API key](https://platform.claude.com/docs/en/manage-claude/admin-api-keys#create-a-key-for-a-claude-enterprise-organization).

40* Your primary owner creates an Admin API key with the `read:plugins` scope, the `write:plugins` scope, or both in [claude.ai > Organization settings > API](https://claude.ai/admin-settings/api-access). See [Create a key for a Claude Enterprise organization](https://platform.claude.com/docs/en/manage-claude/admin-api-keys#create-a-key-for-a-claude-enterprise-organization).

4141* Every request carries three headers: `x-api-key`, `anthropic-version: 2023-06-01`, and `anthropic-beta: ce-plugins-2026-09-01`.

4242

4343The SDK exposes these endpoints under `client.beta.organization` (csharp, go: `client.Beta.Organization`; java: `client.beta().organization()`; php: `$client->beta->organization`), and the [`ant` CLI](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/quickstart) under `ant beta:organization`; they send the `anthropic-version` and `anthropic-beta` headers for you. The examples on this page use the SDK's default client, which, like the CLI, reads the Admin API key from the `ANTHROPIC_API_KEY` environment variable; the curl examples read the key from the same variable and pass it in the `x-api-key` header. Where an SDK or the CLI fetches more pages for you, `limit` sets the page size, not the total (see [Pagination](https://platform.claude.com/docs/en/manage-claude/plugins-api#pagination)).

from line 161

161161 ```

162162</CodeGroup>

163163

164```json

164```text

165165{

166166 "data": [

167167 {

from line 216

216216

217217### Reading another organization under the same parent

218218

219`read:plugins` and `write:plugins` keys read and write only the organization they were created in. If your company has several Claude organizations linked under one parent organization, a `read:org_audit` or `read:compliance_org_data` key that the parent's primary owner created for all linked organizations (see [Create an Admin API key](https://platform.claude.com/docs/en/manage-claude/admin-api-keys#create-a-key-for-a-claude-enterprise-organization)) can also read any of them that has access to this API: pass that organization's ID in the `organization_id` query parameter on any `GET` endpoint on this page. The ID is the organization UUID shown in claude.ai's settings (its `org_`-prefixed form is accepted too). Without the parameter, the key reads the organization it was created in. A `404` means the named organization is not under the key's parent or the API is not available to it; a value that is not a UUID or `org_` ID returns `400`. Any other key that names an organization other than its own gets `404`. Writes do not accept `organization_id`.

219`read:plugins` and `write:plugins` keys read and write only the organization they were created in. If your company has several Claude organizations linked under one parent organization, a `read:org_audit` or `read:compliance_org_data` key that the parent's primary owner created for all linked organizations (see [Create a key for a Claude Enterprise organization](https://platform.claude.com/docs/en/manage-claude/admin-api-keys#create-a-key-for-a-claude-enterprise-organization)) can also read any of them that has access to this API: pass that organization's ID in the `organization_id` query parameter on any `GET` endpoint on this page. The ID is the organization UUID shown in claude.ai's settings (its `org_`-prefixed form is accepted too). Without the parameter, the key reads the organization it was created in. A `404` means the named organization is not under the key's parent or the API is not available to it; a value that is not a UUID or `org_` ID returns `400`. Any other key that names an organization other than its own gets `404`. Writes do not accept `organization_id`.

220220

221221## Key concepts

222222

from line 281

281281| `available` | The plugin can be installed on request. |

282282| `not_available` | The plugin is hidden. |

283283

284A plugin can hold an organization-wide setting and one setting for each group (the role-based access control groups managed in [User management](https://platform.claude.com/docs/en/manage-claude/user-management#groups)). A member gets a value by these rules:

284A plugin can hold an organization-wide setting and one setting for each group (the role-based access control [groups managed in User management](https://platform.claude.com/docs/en/manage-claude/user-management#groups)). A member gets a value by these rules:

285285

2862861. The organization-wide value is the plugin's own organization-wide setting if it has one, otherwise its marketplace's default, otherwise `not_available`. The plugin reports this value in `organization_installation_preference`, with `organization_installation_preference_inherited: true` while it comes from the marketplace default.

2872872. A member who belongs to no group holding a setting for the plugin gets the organization-wide value.

from line 356

356356

357357### Roll a plugin out to a pilot group, then to everyone

358358

3591. Look up the pilot group's ID with `GET /v1/organizations/rbac_groups`. That call needs the `read:rbac_groups` scope, which requires a key created for all linked organizations (see [User management](https://platform.claude.com/docs/en/manage-claude/user-management#groups)). The next steps need `write:plugins`, which acts only on the organization its key was created in, so in an enterprise with several linked organizations, create this key in the organization that holds the plugin and give it both scopes, or use a second key created there for those steps.

3591. Look up the pilot group's ID with `GET /v1/organizations/rbac_groups`. That call needs the `read:rbac_groups` scope, which requires a key created for all linked organizations (see [Groups in User management](https://platform.claude.com/docs/en/manage-claude/user-management#groups)). The next steps need `write:plugins`, which acts only on the organization its key was created in, so in an enterprise with several linked organizations, create this key in the organization that holds the plugin and give it both scopes, or use a second key created there for those steps.

360360

3613612. [Give the group its own setting](https://platform.claude.com/docs/en/manage-claude/plugins-api#set-an-installation-setting), for example `auto_install`, with `POST /v1/organizations/plugins/{plugin_id}/installation_settings/{target}`, where `{target}` is the group's `rbac_group_` ID, while the organization-wide value stays `not_available`. Only the group's members get the plugin.

362362

from line 809

809809 ```

810810</CodeGroup>

811811

812```json

812```text

813813{

814814 "type": "plugin",

815815 "id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",

from line 1256

12561256 ```

12571257</CodeGroup>

12581258

1259```json

1259```text

12601260{

12611261 "type": "plugin",

12621262 "id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",

from line 1393

13931393 ```

13941394</CodeGroup>

13951395

1396```json

1396```text wrap

13971397{ "type": "plugin_deleted", "id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL" }

13981398```

13991399

from line 1675

16751675 ```

16761676</CodeGroup>

16771677

1678```json

1678```text

16791679{

16801680 "type": "plugin_version",

16811681 "id": "pluginver_01Jd5sK2nQ8wE4rT6yU1iO3p",

from line 1970

19701970

19711971## Plugin installation settings

19721972

1973These endpoints apply to organization-owned plugins. They return `404` for a member-owned plugin, which has [shares](https://platform.claude.com/docs/en/manage-claude/plugins-api#plugin-shares) instead. `{target}` is the literal `organization` for the plugin's organization-wide setting, or a group's `rbac_group_` ID for that group's setting; any other value returns `400`. Group IDs come from `GET /v1/organizations/rbac_groups` (scope `read:rbac_groups`; see [User management](https://platform.claude.com/docs/en/manage-claude/user-management#groups)). A setting has no `id` of its own: it is addressed by `(plugin_id, target)`, and no actor is recorded on it (the actor is on its `plugin_installation_preference_updated` activity event).

1973These endpoints apply to organization-owned plugins. They return `404` for a member-owned plugin, which has shares instead (see [Plugin shares](https://platform.claude.com/docs/en/manage-claude/plugins-api#plugin-shares)). `{target}` is the literal `organization` for the plugin's organization-wide setting, or a group's `rbac_group_` ID for that group's setting; any other value returns `400`. Group IDs come from `GET /v1/organizations/rbac_groups` (scope `read:rbac_groups`; see [Groups in User management](https://platform.claude.com/docs/en/manage-claude/user-management#groups)). A setting has no `id` of its own: it is addressed by `(plugin_id, target)`, and no actor is recorded on it (the actor is on its `plugin_installation_preference_updated` activity event).

19741974

19751975### List a plugin's installation settings

19761976

from line 2218

22182218 ```

22192219</CodeGroup>

22202220

2221```json

2221```text

22222222{

22232223 "type": "plugin_installation_setting",

22242224 "plugin_id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",

from line 2338

23382338 ```

23392339</CodeGroup>

23402340

2341```json

2341```text

23422342{

23432343 "type": "plugin_installation_setting_deleted",

23442344 "plugin_id": "plugin_01Hq3vX8kZcN2mB7pR4tY9wL",

from line 2454

24542454 ```

24552455</CodeGroup>

24562456

2457```json

2457```text

24582458{

24592459 "data": [

24602460 {

from line 2472

24722472

24732473This API reads [marketplaces](https://platform.claude.com/docs/en/manage-claude/plugins-api#marketplaces) and sets an organization marketplace's default installation setting; marketplaces themselves are created, connected to a repository, and deleted in claude.ai.

24742474

2475```json

2475```text wrap

24762476{

24772477 "type": "plugin_marketplace",

24782478 "id": "marketplace_01VbNcMxZaSdFgHjKlQwErTy",

from line 2846

28462846

28472847The repository, and any plugin source outside it on GitHub, are read anonymously, so a private repository or private plugin source is reported as not found. Plugin sources on hosts other than GitHub are not fetched; such a plugin normally gets a `marketplace_validate_source_not_checked` warning and is checked when the marketplace actually synchronizes. If the repository is, or the archive names, a marketplace that Anthropic synchronizes into every organization, stricter rules apply: every plugin source outside the marketplace must be pinned to a full commit SHA, unpinned or unsupported-host sources are reported as plugin errors, and the branch read defaults to the one that marketplace synchronizes from.

28482848

2849`validate_repository` takes a JSON body with two fields: `repository_url`, the `https://` URL of a public repository on github.com (required), and `ref`, a branch name or a full 40-character commit SHA (optional; when it is omitted or `null`, the branch a synchronization would read, usually the repository's default branch). `validate_archive` takes `multipart/form-data` with exactly one part, `archive`, sent as a file part with a file name: a `.zip` of the marketplace directory, at most 32 MB, with its contents at the root or wrapped in one folder (as a Git host's download produces), DEFLATE or STORE compression only. No other form field is accepted.

2849`validate_repository` takes a JSON body with two fields: `repository_url`, the `https://` URL of a public repository on github.com (required), and `ref`, a branch name or a full 40-character commit SHA (optional). When `ref` is omitted or `null`, it defaults to the branch a synchronization would read, usually the repository's default branch. `validate_archive` takes `multipart/form-data` with exactly one part, `archive`, sent as a file part with a file name: a `.zip` of the marketplace directory, at most 32 MB, with its contents at the root or wrapped in one folder (as a Git host's download produces), DEFLATE or STORE compression only. No other form field is accepted.

28502850

28512851Validate a public repository at a branch:

28522852

from line 2965

29652965 ```

29662966</CodeGroup>

29672967

2968```json

2968```text wrap

29692969{

29702970 "type": "plugin_marketplace_validation_report",

29712971 "valid": false,

from line 3167

31673167

31683168When one status has several causes that you would handle differently, the error also carries `error.details.error_code`, and `error.details.plugin_id` or `error.details.plugin_version_id` when the cause involves one:

31693169

3170```json

3170```text wrap

31713171{

31723172 "type": "error",

31733173 "error": {

manage-claude/usage-cost-api Changed · +8 / -8 lines

from line 102

102102

103103### Key concepts

104104

105* **Time buckets:** Aggregate usage data in fixed intervals (`1m`, `1h`, or `1d`)

106* **Token tracking:** Measure uncached input, cached input, cache creation, and output tokens

107* **Filtering & grouping:** Filter by API key, workspace, model, service tier, context window, [data residency](https://platform.claude.com/docs/en/manage-claude/data-residency), or speed, and group results by these dimensions

108* **Server tool usage:** Track usage of server-side tools such as web search

105* **Time buckets:** Aggregate usage data in fixed intervals (`1m`, `1h`, or `1d`).

106* **Token tracking:** Measure uncached input, cached input, cache creation, and output tokens.

107* **Filtering & grouping:** Filter by API key, workspace, model, service tier, context window, [data residency](https://platform.claude.com/docs/en/manage-claude/data-residency), or speed, and group results by these dimensions.

108* **Server tool usage:** Track usage of server-side tools such as web search.

109109

110110For complete parameter details and response schemas, see the [Usage API reference](https://platform.claude.com/docs/en/api/beta/organization/usage_report/retrieve_messages).

111111

from line 232

232232

233233### Key concepts

234234

235* **Currency:** All costs in USD, reported as decimal strings in lowest units (cents)

236* **Cost types:** Track token usage, web search, and code execution costs

237* **Grouping:** Group costs by workspace or description for detailed breakdowns. When grouping by `description`, responses include parsed fields such as `model` and `inference_geo`

238* **Time buckets:** Daily granularity only (`1d`)

235* **Currency:** All costs are in USD, reported as decimal strings in lowest units (cents).

236* **Cost types:** Track token usage, web search, and code execution costs.

237* **Grouping:** Group costs by workspace or description for detailed breakdowns. When grouping by `description`, responses include parsed fields such as `model` and `inference_geo`.

238* **Time buckets:** Only daily granularity (`1d`) is available.

239239

240240For complete parameter details and response schemas, see the [Cost API reference](https://platform.claude.com/docs/en/api/beta/organization/cost_report/retrieve).

241241

manage-claude/user-management Changed · +12 / -12 lines

from line 147

147147 ```

148148</CodeGroup>

149149

150```json

150```text wrap

151151{

152152 "data": [

153153 {

from line 604

604604 ```

605605</CodeGroup>

606606

607```json

607```text wrap

608608{

609609 "type": "user_deleted",

610610 "id": "user_01AbCdEfGhIjKlMnOpQrSt"

from line 764

764764 ```

765765</CodeGroup>

766766

767```json

767```text wrap

768768{

769769 "type": "invite",

770770 "id": "invite_01QrStUvWxYzAbCdEfGhIj",

from line 1161

11611161 ```

11621162</CodeGroup>

11631163

1164```json

1164```text wrap

11651165{

11661166 "data": [

11671167 {

from line 1380

13801380 ```

13811381</CodeGroup>

13821382

1383```json

1383```text wrap

13841384{

13851385 "type": "rbac_group",

13861386 "id": "rbac_group_01UvWxYzAbCdEfGhIjKlMn",

from line 1595

15951595 ```

15961596</CodeGroup>

15971597

1598```json

1598```text wrap

15991599{

16001600 "id": "rbac_group_01UvWxYzAbCdEfGhIjKlMn",

16011601 "type": "rbac_group_deleted"

from line 1722

17221722 ```

17231723</CodeGroup>

17241724

1725```json

1725```text wrap

17261726{

17271727 "data": [

17281728 {

from line 1856

18561856 ```

18571857</CodeGroup>

18581858

1859```json

1859```text wrap

18601860{

18611861 "type": "rbac_group_member",

18621862 "rbac_group_id": "rbac_group_01UvWxYzAbCdEfGhIjKlMn",

from line 1975

19751975 ```

19761976</CodeGroup>

19771977

1978```json

1978```text wrap

19791979{

19801980 "rbac_group_id": "rbac_group_01UvWxYzAbCdEfGhIjKlMn",

19811981 "group_id": "rbac_group_01UvWxYzAbCdEfGhIjKlMn",

from line 2091

20912091 ```

20922092</CodeGroup>

20932093

2094```json

2094```text wrap

20952095{

20962096 "data": [

20972097 {

from line 2321

23212321 ```

23222322</CodeGroup>

23232323

2324```json

2324```text wrap

23252325{

23262326 "data": [

23272327 {

from line 2474

24742474

24752475### Can I create or modify groups through the API?

24762476

2477Yes, with the `write:rbac_groups` scope: create, rename, and delete groups, and add or remove their members. Two things the API cannot change: groups provisioned by your identity provider (`source_type: "scim"`), whose name and membership are owned by the identity provider, and custom roles, which are managed in claude.ai organization settings (the API [reads them](https://platform.claude.com/docs/en/manage-claude/user-management#custom-roles)).

2477Yes, with the `write:rbac_groups` scope: create, rename, and delete groups, and add or remove their members. Two things the API cannot change: groups provisioned by your identity provider (`source_type: "scim"`), whose name and membership are owned by the identity provider, and [custom roles](https://platform.claude.com/docs/en/manage-claude/user-management#custom-roles), which are managed in claude.ai organization settings (the API reads them).

24782478

24792479### Does an unaccepted invite consume a seat?

24802480

manage-claude/wif-providers/azure Changed · +4 / -4 lines

from line 673

673673 </Step>

674674

675675 <Step title="Create the annotated Kubernetes service account">

676 The `azure-workload-identity` webhook reads the `azure.workload.identity/client-id` annotation to inject `AZURE_CLIENT_ID` into the pod, which the samples in [Acquire and use the token](https://platform.claude.com/docs/en/manage-claude/wif-providers/azure#acquire-and-use-the-token-2) read from the environment.

676 The `azure-workload-identity` webhook reads the `azure.workload.identity/client-id` annotation to inject `AZURE_CLIENT_ID` into the pod, which the samples in [Acquire and use the token on AKS](https://platform.claude.com/docs/en/manage-claude/wif-providers/azure#acquire-and-use-the-token-2) read from the environment.

677677

678678 ```yaml

679679 apiVersion: v1

from line 720

720720 </Step>

721721

722722 <Step title="Decode a sample token">

723 The token your Anthropic federation rule sees is not the projected file; it is the Entra-issued token returned by the `client_credentials` exchange. From inside a labeled pod, run step 1 of the cURL sample in [Acquire and use the token](https://platform.claude.com/docs/en/manage-claude/wif-providers/azure#acquire-and-use-the-token-2) and decode the result. It carries the same claim shape as the managed identity path:

723 The token your Anthropic federation rule sees is not the projected file; it is the Entra-issued token returned by the `client_credentials` exchange. From inside a labeled pod, run step 1 of the cURL sample in [Acquire and use the token on AKS](https://platform.claude.com/docs/en/manage-claude/wif-providers/azure#acquire-and-use-the-token-2) and decode the result. It carries the same claim shape as the managed identity path:

724724

725725 ```json

726726 {

from line 1241

12411241

12421242### Verify the setup

12431243

1244From inside a labeled pod, run the cURL exchange shown in [Acquire and use the token](https://platform.claude.com/docs/en/manage-claude/wif-providers/azure#acquire-and-use-the-token-2) and confirm that `POST /v1/oauth/token` returns a `200` with an `access_token` beginning with `sk-ant-oat01-` and an `expires_in` value in seconds. If the exchange fails with the opaque `401` `authentication_error` response (message `Authentication failed`), check the [authentication history page](https://platform.claude.com/settings/workload-identity-federation?tab=history) in the Claude Console for the deny reason, then decode the Entra-issued token from step 1 (see [Troubleshoot a failed exchange](https://platform.claude.com/docs/en/manage-claude/wif-reference#troubleshoot-a-failed-exchange) for the command) and check the most common Azure-side causes:

1244From inside a labeled pod, run the cURL exchange shown in [Acquire and use the token on AKS](https://platform.claude.com/docs/en/manage-claude/wif-providers/azure#acquire-and-use-the-token-2) and confirm that `POST /v1/oauth/token` returns a `200` with an `access_token` beginning with `sk-ant-oat01-` and an `expires_in` value in seconds. If the exchange fails with the opaque `401` `authentication_error` response (message `Authentication failed`), check the [authentication history page](https://platform.claude.com/settings/workload-identity-federation?tab=history) in the Claude Console for the deny reason, then decode the Entra-issued token from step 1 (see [Troubleshoot a failed exchange](https://platform.claude.com/docs/en/manage-claude/wif-reference#troubleshoot-a-failed-exchange) for the command) and check the most common Azure-side causes:

12451245

12461246* **Issuer mismatch:** The registered `issuer_url` must match the token's `iss` claim exactly. A v2.0 token carries `https://login.microsoftonline.com/<TENANT_ID>/v2.0`; if the decoded `ver` claim is `1.0`, see [If your tokens are v1.0](https://platform.claude.com/docs/en/manage-claude/wif-providers/azure#if-your-tokens-are-v1-0).

1247* **Token lifetime:** If a tenant token-lifetime policy or CAE extends the `client_credentials` token past 7,500 seconds, raise the issuer's `max_jwt_lifetime_seconds` as described in [Configure Anthropic](https://platform.claude.com/docs/en/manage-claude/wif-providers/azure#configure-anthropic-2).

1247* **Token lifetime:** If a tenant token-lifetime policy or CAE extends the `client_credentials` token past 7,500 seconds, raise the issuer's `max_jwt_lifetime_seconds` as described in [Configure Anthropic for Entra Workload Identity on AKS](https://platform.claude.com/docs/en/manage-claude/wif-providers/azure#configure-anthropic-2).

12481248* **Audience mismatch:** The rule's `audience` must equal the token's `aud` exactly: the audience app registration's client ID for the v2.0 tokens this guide configures.

12491249* **Claim name mismatch:** A rule that matches on a claim the token does not carry never passes. v1.0 tokens carry the client ID in `appid`, not `azp`; see [If your tokens are v1.0](https://platform.claude.com/docs/en/manage-claude/wif-providers/azure#if-your-tokens-are-v1-0).

12501250

manage-claude/workspaces Changed · +8 / -8 lines

from line 12

1212

1313Key characteristics:

1414

15* **Workspace identifiers** use the `wrkspc_` prefix (for example, `wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ`)

16* **Maximum 100 workspaces** for each organization by default (archived workspaces don't count); contact your account team if you need more

17* **Default Workspace** has a `wrkspc_` ID like any other workspace (returned in the [`anthropic-workspace-id` response header](https://platform.claude.com/docs/en/manage-claude/workspaces#identify-the-workspace-behind-an-api-response) and accepted by [Get Workspace](https://platform.claude.com/docs/en/api/organization/workspaces/retrieve)), but it appears in [List Workspaces](https://platform.claude.com/docs/en/api/organization/workspaces/list) results only when you pass `include_default=true`, and usage reports and cost reports show `null` for its `workspace_id` (an API key's `scope` field carries the real ID for a key bound to the Default Workspace)

18* **API keys** can be scoped to a single workspace. In this case, they can only access resources within that workspace. Other API keys aren't scoped to a workspace. With one of these keys, send a [workspace ID header](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) on each request to choose the workspace. The key's user or service account must have access to that workspace

15* **Workspace identifiers** use the `wrkspc_` prefix (for example, `wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ`).

16* **Maximum 100 workspaces** for each organization by default (archived workspaces don't count). Contact your account team if you need more.

17* **Default Workspace** has a `wrkspc_` ID like any other workspace (returned in the [`anthropic-workspace-id` response header](https://platform.claude.com/docs/en/manage-claude/workspaces#identify-the-workspace-behind-an-api-response) and accepted by [Get Workspace](https://platform.claude.com/docs/en/api/organization/workspaces/retrieve)), but it appears in [List Workspaces](https://platform.claude.com/docs/en/api/organization/workspaces/list) results only when you pass `include_default=true`, and usage reports and cost reports show `null` for its `workspace_id` (an API key's `scope` field carries the real ID for a key bound to the Default Workspace).

18* **API keys** can be scoped to a single workspace. In this case, they can only access resources within that workspace. Other API keys aren't scoped to a workspace. With one of these keys, send a [workspace ID header](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) on each request to choose the workspace. The key's user or service account must have access to that workspace.

1919

2020### Claude Code workspace

2121

from line 25

2525

2626* Claude Code mints a per-user API key in this workspace at sign-in. You cannot create keys in it manually from the Console.

2727* A Claude Code key stops working if its owner is removed from the workspace or organization, unlike a workspace key.

28* Claude Code usage is rate-limited separately, and admins can cap its share of the organization's limits on the [Rate limits](https://platform.claude.com/usage/limits) page in the Claude Console.

28* Claude Code usage is rate-limited separately, and admins can cap its share of the organization's limits under [Rate limits in the Claude Console](https://platform.claude.com/usage/limits).

2929* It is the only workspace that supports per-user monthly spend limits.

3030

3131<Warning>

from line 122

122122

123123You set a workspace's rate limits and spend limits in different places:

124124

125* **Rate limits:** On the [Rate limits](https://platform.claude.com/usage/limits) page in the Claude Console, select the workspace from the **Workspace** dropdown menu and click **Edit** next to a model to set limits for requests per minute, input tokens, or output tokens.

125* **Rate limits:** Under [Rate limits in the Claude Console](https://platform.claude.com/usage/limits), select the workspace from the **Workspace** dropdown menu and click **Edit** next to a model to set limits for requests per minute, input tokens, or output tokens.

126126* **Spend limits:** On the [Workspaces](https://platform.claude.com/settings/workspaces) page in the Claude Console, select the workspace. In the panel that opens, click **Spend limits** to cap monthly spending and configure alerts when spending reaches certain thresholds.

127127

128128#### Archive a workspace

from line 849

849849

850850Claude API responses include an `anthropic-workspace-id` header alongside the `request-id` and `anthropic-organization-id` [response headers](https://platform.claude.com/docs/en/api/overview#response-headers). Its value is the `wrkspc_`-prefixed ID of the workspace that the request's API key or access token resolved to, including when that workspace is the Default Workspace. For example, a successful response includes headers like these:

851851

852```http

852```text wrap

853853HTTP/1.1 200 OK

854854request-id: req_018EeWyXxfu5pfWkrYcMdjWG

855855anthropic-organization-id: 0d0e7a3b-52f1-4c7e-9a51-3f6f2f7c1b9e

from line 1023

10231023You can set workspace limits lower than (but not higher than) your organization's limits:

10241024

10251025* **Spend limits:** Cap monthly spending for a workspace. To set these, go to the [Workspaces](https://platform.claude.com/settings/workspaces) page (`platform.claude.com/settings/workspaces`) in the Claude Console and select the workspace. In the panel that opens, click **Spend limits**.

1026* **Rate limits:** Limit requests per minute, input tokens per minute, or output tokens per minute. To set these, go to the [Rate limits](https://platform.claude.com/usage/limits) page in the Claude Console, select the workspace from the **Workspace** dropdown menu, and click **Edit** next to a model.

1026* **Rate limits:** Limit requests per minute, input tokens per minute, or output tokens per minute. To set these, go to [Rate limits in the Claude Console](https://platform.claude.com/usage/limits), select the workspace from the **Workspace** dropdown menu, and click **Edit** next to a model.

10271027

10281028<Note>

10291029 - You cannot set spend limits on the Default Workspace.

managed-agents/agent-setup Changed · +13 / -13 lines

from line 16

1616

1717## Agent configuration fields

1818

19| Field | Description |

20| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

21| `name` (csharp, go: `Name`) | Required. A human-readable name for the agent. |

22| `model` (csharp, go: `Model`) | Required. The Claude [model](https://platform.claude.com/docs/en/models/overview) that powers the agent. Accepts a model ID string or an object, for example `{"id": "claude-opus-5-5"}`. Claude 4.5 and later models are supported. The object form also accepts `speed`, `effort`, and `inference_geo` fields; see the tips under [Create an agent](https://platform.claude.com/docs/en/managed-agents/agent-setup#create-an-agent), [Effort levels](https://platform.claude.com/docs/en/build-with-claude/effort#effort-levels), and [Pin the inference geo](https://platform.claude.com/docs/en/managed-agents/agent-setup#pin-the-inference-geo). |

23| `system` (csharp, go: `System`; ruby: `system_`) | A [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role) that defines the agent's behavior and persona. The system prompt is distinct from [user messages](https://platform.claude.com/docs/en/managed-agents/reference#event-types), which should describe the work to be done. |

24| `tools` (csharp, go: `Tools`) | The tools available to the agent. Combines [pre-built agent tools](https://platform.claude.com/docs/en/managed-agents/tools), [MCP tools](https://platform.claude.com/docs/en/managed-agents/mcp-connector), and [custom tools](https://platform.claude.com/docs/en/managed-agents/tools#custom-tools). |

25| `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) | [MCP servers](https://platform.claude.com/docs/en/managed-agents/mcp-connector) that provide standardized third-party capabilities. |

26| `skills` (csharp, go: `Skills`) | [Skills](https://platform.claude.com/docs/en/managed-agents/skills) that supply domain-specific context with progressive disclosure. |

27| `multiagent` (csharp, go: `Multiagent`) | Lets the agent hand work to other agents, as subagents or in [dynamic workflows](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#dynamic-workflows), and optionally consult an [advisor](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#give-the-session-an-advisor) model. With the `multiagent_20261001` type, dynamic workflows are on unless you disable them. See [Multiagent orchestration](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration). |

28| `description` (csharp, go: `Description`) | A description of what the agent does. |

29| `metadata` (csharp, go: `Metadata`) | Arbitrary key-value pairs for your own tracking. |

19| Field | Description |

20| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

21| `name` (csharp, go: `Name`) | Required. A human-readable name for the agent. |

22| `model` (csharp, go: `Model`) | Required. The Claude [model](https://platform.claude.com/docs/en/models/overview) that powers the agent. Accepts a model ID string or an object, for example `{"id": "claude-opus-5-5"}`. Claude 4.5 and later models are supported. The object form also accepts `speed` (csharp, go: `Speed`), `effort` (csharp, go: `Effort`), and `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) fields; see the tips under [Create an agent](https://platform.claude.com/docs/en/managed-agents/agent-setup#create-an-agent), [Effort levels](https://platform.claude.com/docs/en/build-with-claude/effort#effort-levels), and [Pin the inference geo](https://platform.claude.com/docs/en/managed-agents/agent-setup#pin-the-inference-geo). |

23| `system` (csharp, go: `System`; ruby: `system_`) | A [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role) that defines the agent's behavior and persona. The system prompt is distinct from [user messages](https://platform.claude.com/docs/en/managed-agents/reference#event-types), which should describe the work to be done. |

24| `tools` (csharp, go: `Tools`) | The tools available to the agent. Combines [pre-built agent tools](https://platform.claude.com/docs/en/managed-agents/tools), [MCP tools](https://platform.claude.com/docs/en/managed-agents/mcp-connector), and [custom tools](https://platform.claude.com/docs/en/managed-agents/tools#custom-tools). |

25| `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) | [MCP servers](https://platform.claude.com/docs/en/managed-agents/mcp-connector) that provide standardized third-party capabilities. |

26| `skills` (csharp, go: `Skills`) | [Skills](https://platform.claude.com/docs/en/managed-agents/skills) that supply domain-specific context with progressive disclosure. |

27| `multiagent` (csharp, go: `Multiagent`) | Lets the agent hand work to other agents, as subagents or in [dynamic workflows](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#dynamic-workflows), and optionally consult an [advisor](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#give-the-session-an-advisor) model. With the `multiagent_20261001` type, dynamic workflows are on unless you disable them. See [Multiagent orchestration](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration). |

28| `description` (csharp, go: `Description`) | A description of what the agent does. |

29| `metadata` (csharp, go: `Metadata`) | Arbitrary key-value pairs for your own tracking. |

3030

3131You can also override `model` (csharp, go: `Model`), `system` (csharp, go: `System`; ruby: `system_`), `tools` (csharp, go: `Tools`), `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`), and `skills` (csharp, go: `Skills`) for a single session without changing the agent. A `model` (csharp, go: `Model`) override replaces the agent's `model` (csharp, go: `Model`) object in full, so the agent's own `effort` (csharp, go: `Effort`) isn't carried over. To run the session at a specific effort level, set `effort` (csharp, go: `Effort`) inside the override's `model` (csharp, go: `Model`) object. See [Override agent configuration for a session](https://platform.claude.com/docs/en/managed-agents/sessions#override-agent-configuration-for-a-session).

3232

from line 154

154154

155155The response echoes your configuration and adds `id`, `type`, `version`, `created_at`, `updated_at`, and `archived_at` fields, and fills in `model` fields you omit, such as `effort`, with their defaults. The `version` starts at 1 and increments each time an update changes the agent.

156156

157```json

157```text wrap

158158{

159159 "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",

160160 "type": "agent",

from line 445

445445 ```

446446</CodeGroup>

447447

448The preceding example supplies `version` from the create response, so the update only applies if nothing else has changed the agent since you read it. To apply an update unconditionally, omit `version` from the request:

448The preceding example supplies `version` (csharp, go: `Version`) from the create response, so the update only applies if nothing else has changed the agent since you read it. To apply an update unconditionally, omit `version` (csharp, go: `Version`) from the request:

449449

450450<CodeGroup>

451451 ```bash cURL

managed-agents/define-outcomes Changed · +6 / -6 lines

from line 551

551551

552552Emitted once the grader starts an evaluation over one iteration loop. The `iteration` field is a 0-indexed revision counter: `0` is the first evaluation, `1` is the re-evaluation after the first revision, and so on.

553553

554```json

554```text wrap

555555{

556556 "type": "span.outcome_evaluation_start",

557557 "id": "sevt_01def...",

from line 563

563563

564564### Outcome evaluation ongoing

565565

566Heartbeat emitted while the grader runs. The grader's internal reasoning is opaque: you see that it's working, not what it's thinking.

566Heartbeat emitted while the grader runs. The grader's internal reasoning is opaque: the event shows only that the grader is working.

567567

568```json

568```text wrap

569569{

570570 "type": "span.outcome_evaluation_ongoing",

571571 "id": "sevt_01ghi...",

from line 587

587587| `failed` | Session transitions to `idle`. Returned when the rubric does not apply to the deliverables, for example if the description and rubric contradict each other. |

588588| `interrupted` | Emitted when the session is interrupted while an outcome is active, even if evaluation hadn't started yet. If no `outcome_evaluation_start` fired before the interrupt, `outcome_evaluation_start_id` is an empty string. |

589589

590```json

590```text

591591{

592592 "type": "span.outcome_evaluation_end",

593593 "id": "sevt_01jkl...",

from line 691

691691

692692## Retrieve deliverables

693693

694The agent writes output files to `/mnt/session/outputs/` inside the sandbox. To retrieve them, list files through the [Files API](https://platform.claude.com/docs/en/build-with-claude/files) with the session ID as the `scope_id` (java: `scopeId`; php: `scopeID`; csharp, go: `ScopeID`), then download them by ID. Filtering by `scope_id` (java: `scopeId`; php: `scopeID`; csharp, go: `ScopeID`) requires the `managed-agents-2026-04-01` beta header on the list request, so the SDK and CLI examples make that call through the `beta` namespace and pass the header explicitly. Files appear in the list shortly after the agent finishes writing them, sometimes a few seconds after the session goes idle. If a file you expect is not listed yet, list again after a short delay; once it appears in the list, its upload has finished.

694The agent writes output files to `/mnt/session/outputs/` inside the sandbox. To retrieve them, list files through the [Files API](https://platform.claude.com/docs/en/build-with-claude/files) with the session ID as the `scope_id` (java: `scopeId`; php: `scopeID`; csharp, go: `ScopeID`), then download them by ID. Filtering by `scope_id` (java: `scopeId`; php: `scopeID`; csharp, go: `ScopeID`) requires the `managed-agents-2026-04-01` beta header on the list request, so the SDK and CLI examples make that call through the `beta` namespace and pass the header explicitly. Files appear in the list shortly after the agent finishes writing them, sometimes a few seconds after the session goes idle. If a file you expect is not listed yet, list again after a short delay; once it appears in the list, its upload is complete.

695695

696696<CodeGroup>

697697 ```bash cURL

managed-agents/event-deltas Changed · +3 / -3 lines

from line 31

3131

3232When a previewed event starts, the stream emits an `event_start` carrying the upcoming event's type and `id`:

3333

34```json

34```text wrap

3535{

3636 "type": "event_start",

3737 "event": {

from line 43

4343

4444For `agent.message`, the start is followed by `event_delta` events carrying incremental text. Each delta names the event it extends in `event_id` and the content block it extends in `delta.index`:

4545

46```json

46```text wrap

4747{

4848 "type": "event_delta",

4949 "event_id": "sevt_01abc...",

from line 68

6868

6969## Accumulate and reconcile

7070

71Every SDK that supports event deltas includes an [accumulator helper](https://platform.claude.com/docs/en/managed-agents/event-deltas#sdk-accumulator-helpers) that handles the `index` bookkeeping for you. The manual pattern in this section works in every language when you need custom bookkeeping. Apply it to the generated event types.

71Every SDK that supports event deltas includes an [accumulator helper](https://platform.claude.com/docs/en/managed-agents/event-deltas#sdk-accumulator-helpers) that handles the `index` (csharp, go: `Index`) bookkeeping for you. The manual pattern in this section works in every language when you need custom bookkeeping. Apply it to the generated event types.

7272

7373In the manual pattern, hold preview text in a temporary map keyed by `(event_id, index)`, and treat the buffered event as the record. Reconcile the two for each model request.

7474

managed-agents/memory Changed · +3 / -3 lines

from line 370

370370

371371A maximum of **8 memory stores** is supported for each session. Attach multiple stores when different parts of memory have different owners or access rules. Common reasons:

372372

373* **Shared reference material:** one read-only store attached to many sessions (standards, conventions, domain knowledge), kept separate from each session's own read-write store.

374* **Mapping to your product's structure:** one store for each end user, team, or project, while sharing a single agent configuration.

375* **Different lifecycles:** a store that outlives any single session, or one you want to archive on its own schedule.

373* **Shared reference material:** one read-only store attached to many sessions (standards, conventions, domain knowledge), kept separate from each session's own read-write store

374* **Mapping to your product's structure:** one store for each end user, team, or project, while sharing a single agent configuration

375* **Different lifecycles:** a store that outlives any single session, or one you want to archive on its own schedule

376376

377377### How the agent accesses memory

378378

managed-agents/multiagent-orchestration Changed · +6 / -6 lines

from line 846

846846

847847### Turn on dynamic workflows

848848

849When [defining your agent](https://platform.claude.com/docs/en/managed-agents/agent-setup), set `multiagent.type` to `"multiagent_20261001"` and enable `workflows`. Dynamic workflows and delegating (`subagents`) are both on by default with this type. For dynamic workflows only, add `"subagents": {"type": "disabled"}`.

849When [defining your agent](https://platform.claude.com/docs/en/managed-agents/agent-setup), set `multiagent.type` to `"multiagent_20261001"` and enable `workflows` (csharp, go: `Workflows`). Dynamic workflows and delegating (`subagents` (csharp, go: `Subagents`)) are both on by default with this type. For dynamic workflows only, also set `subagents` (csharp, go: `Subagents`) to `{"type": "disabled"}`.

850850

851851Before you change an existing agent's `multiagent.type`, see [how to move an agent to this type](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#move-from-the-coordinator-type).

852852

from line 1026

10261026 * A setting or field you send as `null` takes its default, and so does everything inside it, whatever you had stored.

10271027 * A `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) list you send replaces the stored list.

10281028 * A setting you send with a different `type` replaces the stored setting, and the fields you leave out of it take their defaults.

1029 * Every object you send needs its `type`, and an enabled `advisor` needs its `model`.

1029 * Every object you send needs its `type`, and an enabled `advisor` (csharp, go: `Advisor`) needs its `model` (csharp, go: `Model`).

10301030

1031* **Turning it off:** Set `workflows` to `{"type": "disabled"}`. It stays off until an update turns it on again. Sending `null` turns it on, because its default is enabled. The same applies to `subagents`.

1031* **Turning it off:** Set `workflows` (csharp, go: `Workflows`) to `{"type": "disabled"}`. It stays off until an update turns it on again. Sending `null` turns it on, because its default is enabled. The same applies to `subagents` (csharp, go: `Subagents`).

10321032

10331033* **Existing sessions:** A session copies the setting when it is created, so changing the agent later doesn't change a session that already exists.

10341034

from line 1061

10611061

10621062## Give the session an advisor

10631063

1064An enabled `advisor` setting in the agent's `multiagent` (csharp, go: `Multiagent`) block gives the session's primary thread an **advisor:** a model it can consult mid-turn for strategic guidance, such as planning an approach, getting unstuck, or reviewing work before finishing. The setting is disabled by default. To enable it, set `advisor` to `{"type": "enabled", "model": "..."}`, which has exactly two fields, `type` and `model`:

1064An enabled `advisor` (csharp, go: `Advisor`) setting in the agent's `multiagent` (csharp, go: `Multiagent`) block gives the session's primary thread an **advisor:** a model it can consult mid-turn for strategic guidance, such as planning an approach, moving past an obstacle, or reviewing work before finishing. The setting is disabled by default. To enable it, set `advisor` (csharp, go: `Advisor`) to `{"type": "enabled", "model": "..."}`, which has exactly two fields, `type` and `model`:

10651065

10661066<CodeGroup defaultLanguage="CLI">

10671067 ```bash cURL

from line 1242

12421242

12431243### Removing the advisor

12441244

1245To remove the advisor, [update the agent](https://platform.claude.com/docs/en/managed-agents/agent-setup#update-an-agent) with `advisor` set to `{"type": "disabled"}`. On an agent that already has the `multiagent_20261001` type, a setting that the update leaves out keeps its stored value, so you don't need to send `subagents` or `workflows` again. For the same reason, an update that leaves `advisor` out keeps the advisor. Before you change an existing agent's `multiagent.type`, see [how to move an agent to this type](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#move-from-the-coordinator-type).

1245To remove the advisor, [update the agent](https://platform.claude.com/docs/en/managed-agents/agent-setup#update-an-agent) with `advisor` (csharp, go: `Advisor`) set to `{"type": "disabled"}`. On an agent that already has the `multiagent_20261001` type, a setting that the update leaves out keeps its stored value, so you don't need to send `subagents` (csharp, go: `Subagents`) or `workflows` (csharp, go: `Workflows`) again. For the same reason, an update that leaves `advisor` (csharp, go: `Advisor`) out keeps the advisor. Before you change an existing agent's `multiagent.type`, see [how to move an agent to this type](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#move-from-the-coordinator-type).

12461246

12471247## Move from the `coordinator` type

12481248

managed-agents/permission-policies Changed · +4 / -4 lines

from line 993

993993

994994For example, when `bash` is under `auto` and the server evaluates a call as high-risk, the denied call appears on the event stream as follows:

995995

996```json

996```text wrap

997997{

998998 "type": "agent.tool_use",

999999 "id": "sevt_01pqr...",

from line 1040

10401040

10411041For example, a `bash` call paused under an `always_ask` policy appears on the stream as follows:

10421042

1043```json

1043```text wrap

10441044{

10451045 "type": "agent.tool_use",

10461046 "id": "sevt_01def...",

from line 1060

10601060

10611061To answer interactively instead, use `ant beta:sessions connect`, which shows the waiting call and sends this event when you allow or deny it. See [Connect to a Managed Agents session from your terminal](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/sessions-connect#follow-and-steer-the-session).

10621062

1063In the following examples, the tool-use event IDs come from the `stop_reason.event_ids` array of the `session.status_idle` event. Learn more about receiving events in the [Session event stream](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#stream-events) guide, or [subscribe to webhooks](https://platform.claude.com/docs/en/managed-agents/webhooks) to be notified when a session pauses for input.

1063In the following examples, the tool-use event IDs come from the `stop_reason.event_ids` array of the `session.status_idle` event. Learn more about [receiving events](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#stream-events) in the Session event stream guide, or [subscribe to webhooks](https://platform.claude.com/docs/en/managed-agents/webhooks) to be notified when a session pauses for input.

10641064

10651065<CodeGroup>

10661066 ```bash cURL

from line 1309

13091309

13101310## Custom tools

13111311

1312Permission policies do not apply to custom tools. When the agent invokes a custom tool, your application receives an `agent.custom_tool_use` event and is responsible for deciding whether to run it before sending back a `user.custom_tool_result`. See [Answer tool calls that pause the session](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#answer-tool-calls-that-pause-the-session) for the full flow.

1312Permission policies do not apply to custom tools. When the agent calls a custom tool, your application receives an `agent.custom_tool_use` event and is responsible for deciding whether to run it before sending back a `user.custom_tool_result`. See [Answer tool calls that pause the session](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#answer-tool-calls-that-pause-the-session) for the full flow.

13131313

13141314## Next steps

13151315

managed-agents/secure-deployment Changed · +4 / -4 lines

from line 226

226226 After you tighten an environment, start new sessions and stop the ones that were already running. A session that is already running can keep the old limits until it ends. See [Set limits and a way to stop](https://platform.claude.com/docs/en/managed-agents/secure-deployment#set-limits-and-a-way-to-stop).

227227</Note>

228228

229See [Cloud environment setup](https://platform.claude.com/docs/en/managed-agents/environments#networking) for every networking setting.

229See [Networking in Cloud environment setup](https://platform.claude.com/docs/en/managed-agents/environments#networking) for every networking setting.

230230

231231## Keep credentials in vaults

232232

from line 806

807807| -------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |

808808| Lead (the agent that the session runs) | Your message, and what the other agents send back | No built-in tools. The `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) list of its `subagents` (csharp, go: `Subagents`) names the fetcher and the writer | A task to each agent |

809| Fetcher | Web pages and search results | `web_fetch` and `web_search` only, each with `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) | Short results, in a format you ask for in its system prompt |

809| Fetcher | Webpages and search results | `web_fetch` and `web_search` only, each with `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) | Short results, in a format you ask for in its system prompt |

811811

812812The fetcher's results are built from untrusted pages, and the lead can pass their text on to the writer. Keep `auto` or `always_ask` on the writer's tools. The fetcher can still send some of what it reads to the sites on its `web_fetch` list, and to the search provider in its queries.

from line 822

822822| Session budget | A cap on spend at public list prices. At the cap, the session and each [thread](https://platform.claude.com/docs/en/managed-agents/session-threads) pause. Requests in progress can complete and their tool calls still run, so spend can pass the cap. See [When a session reaches its budget](https://platform.claude.com/docs/en/managed-agents/budgets#when-a-session-reaches-its-budget) |

823823| Deployment budget | The same cap, applied to each session a deployment starts |

824824| [`user.interrupt` event](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#interrupt-the-agent) | Stops the model response immediately. A running tool call can complete first. The session goes `idle`, unless a workflow run keeps it `running`, and resumes on your next message. An interrupt ends no workflow run |

825| Archive or delete a session | Archiving keeps the history and blocks new events. Deleting removes the record, events, and sandbox |

825| Archive or delete a session | Archiving keeps the history and blocks new events. Deleting is permanent. It deletes the record, events, and sandbox |

826826| Pause or archive a deployment | Pausing stops new scheduled runs but still allows manual runs. Archiving ends the schedule permanently. Sessions already running keep running |

827827| Archive or delete a vault or credential | Removes the secret from running sessions without a restart. Allow for a delay. The sessions keep running, so interrupt them too. A token the agent already fetched with the secret stays in the sandbox |

828828

from line 837

837837

838838An interrupt does not undo what the agent already did or sent. Archiving an agent does not stop its running sessions.

839839

840A budget's `max_list_cost.amount` (java, php: `maxListCost.amount`; csharp, go: `MaxListCost.Amount`) is a whole number of US cents written as a string, so `"125"` means $1.25. See [Set a budget at session creation](https://platform.claude.com/docs/en/managed-agents/budgets#set-a-budget-at-session-creation).

840A budget's `max_list_cost.amount` (java, php: `maxListCost.amount`; csharp, go: `MaxListCost.Amount`) is a whole number of US cents written as a string, so `"125"` means $1.25 USD. See [Set a budget at session creation](https://platform.claude.com/docs/en/managed-agents/budgets#set-a-budget-at-session-creation).

841841

842842You cannot add a budget to a session created without one. To change or remove a cap, see [Resume a session at its budget](https://platform.claude.com/docs/en/managed-agents/budgets#resume-a-session-at-its-budget). After you remove a session's cap, you cannot set a new one.

843843

managed-agents/sessions Changed · +3 / -3 lines

from line 434

434434

435435* **Set the field to `null`, or to an empty array for list fields:** The session runs with that field cleared. This rule applies in full to `system` (csharp, go: `System`; ruby: `system_`) and `skills` (csharp, go: `Skills`). There are three exceptions:

436436

437 * `model` is never clearable. A session always needs a model, so `model: null` returns a 400 `agent_model_required` error.

438 * Clearing `tools` returns a 400 error when the session's effective `skills` (csharp, go: `Skills`) is non-empty, because skills require the `read` tool. Otherwise, `tools: null` and `tools: []` clear the field.

437 * `model` (csharp, go: `Model`) is never clearable. A session always needs a model, so setting `model` (csharp, go: `Model`) to `null` returns a 400 `agent_model_required` error.

438 * Clearing `tools` (csharp, go: `Tools`) returns a 400 error when the session's effective `skills` (csharp, go: `Skills`) is non-empty, because skills require the `read` tool. Otherwise, setting `tools` (csharp, go: `Tools`) to `null` or to an empty array clears the field.

439439 * Clearing `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) returns a 400 error when the session's effective `tools` (csharp, go: `Tools`) still contains an `mcp_toolset` that references one of the agent's servers. Override `tools` (csharp, go: `Tools`) in the same request to remove those `mcp_toolset` entries, then clear `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`).

440440

441441* **Set the field to a value:** The value replaces the agent's value in full. Overrides never merge with the agent's configuration, so a `tools` (csharp, go: `Tools`) override must list every tool the session should have. Likewise, a `model` (csharp, go: `Model`) override replaces the agent's `model` (csharp, go: `Model`) object in full, so the agent's own `effort` (csharp, go: `Effort`) isn't carried over. To run the session at a specific effort level, set `effort` (csharp, go: `Effort`) inside the override's `model` (csharp, go: `Model`) object. A level the model doesn't support returns a 400 error, and a `model` (csharp, go: `Model`) override without `effort` (csharp, go: `Effort`) runs at that model's default effort level.

from line 754

754754

755755### Set a session budget

756756

757To cap what a session can spend, pass the optional `budget` (csharp, go: `Budget`) object when you create it. A budget is a hard ceiling on the session's list cost: the platform prices everything the session consumes at public list rates, and the session stops issuing new model requests once that running total reaches `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`). The budget's `type` (csharp, go: `Type`) is always `limit`. Give `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`) an `amount` (csharp, go: `Amount`) and a `currency` (csharp, go: `Currency`). `amount` (csharp, go: `Amount`) is a whole number of US cents written as a string, such as `"125"` for $1.25 USD. The API takes a string rather than a number so no floating-point rounding is ever applied. `USD` is the only currency currently supported. When the session reaches the cap, it pauses and goes idle with the stop reason `budget_reached`. The cap is enforced between model requests, so the request that crosses it completes first and the session's final list cost can land [a fraction past the cap](https://platform.claude.com/docs/en/managed-agents/budgets#when-a-session-reaches-its-budget). A budget can only be attached at creation: you can [change or remove](https://platform.claude.com/docs/en/managed-agents/session-operations#updating-the-session-budget) it later, but you can't add one to a session created without it.

757To cap what a session can spend, pass the optional `budget` (csharp, go: `Budget`) object when you create it. A budget is a hard ceiling on the session's list cost: the platform prices everything the session consumes at public list rates, and the session stops issuing new model requests once that running total reaches `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`). The budget's `type` (csharp, go: `Type`) is always `limit`. Give `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`) an `amount` (csharp, go: `Amount`) and a `currency` (csharp, go: `Currency`). `amount` (csharp, go: `Amount`) is a whole number of US cents written as a string, such as `"125"` for $1.25 USD. The API takes a string rather than a number so no floating-point rounding is ever applied. `USD` is the only currency currently supported. When the session reaches the cap, it pauses and goes idle with the stop reason `budget_reached`. The cap is enforced between model requests, so the request that crosses it completes first and the session's final list cost can land [a fraction past the cap](https://platform.claude.com/docs/en/managed-agents/budgets#when-a-session-reaches-its-budget). A budget can only be attached at creation: you can [change or remove the budget](https://platform.claude.com/docs/en/managed-agents/session-operations#updating-the-session-budget) later, but you can't add one to a session created without it.

758758

759759The following example creates a session with a $1.25 USD budget:

760760

managed-agents/tools-web-restrictions Changed · +4 / -4 lines

from line 462

462462

463463In a [multiagent session](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration), every domain list that applies to a thread is enforced at the same time. An agent listed in the `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) list of `subagents` (csharp, go: `Subagents`) is bound by three sets of per-tool lists:

464464

465* Its own `allowed_domains` and `blocked_domains`

465* Its own `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) and `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`)

466466* Those of any agent that called it

467467* The current lists of the agent that the session runs

468468

from line 476

476476

477477A listed agent can therefore narrow what a tool reaches but never widen it:

478478

479* A listed agent that sets `blocked_domains` keeps the `allowed_domains` of the session's agent and blocks those hosts within it.

480* A listed agent that sets its own `allowed_domains` can reach only the hosts that both its list and the list of the session's agent cover.

479* A listed agent that sets `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`) keeps the `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) of the session's agent and blocks those hosts within it.

480* A listed agent that sets its own `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) can reach only the hosts that both its list and the list of the session's agent cover.

481481

482482A `{"type": "self"}` entry in the `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) list of `subagents` (csharp, go: `Subagents`) has no web settings of its own and follows the current settings of the session's agent.

483483

484If the combined `allowed_domains` lists have no domain in common, the tool stays available to that agent, but every call fails. Each call returns a `url_not_allowed` error stating that no domain is permitted. The tool description tells the model the same. To avoid this, keep each listed agent's `allowed_domains` inside the `allowed_domains` of the session's agent.

484If the combined `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) lists have no domain in common, the tool stays available to that agent, but every call fails. Each call returns a `url_not_allowed` error stating that no domain is allowed. The tool description tells the model the same. To avoid this, keep each listed agent's `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) inside the `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) of the session's agent.

485485

486486The grader in [outcome-driven sessions](https://platform.claude.com/docs/en/managed-agents/define-outcomes) runs without `web_search` and `web_fetch`, regardless of these settings.

487487

managed-agents/vaults Changed · +4 / -4 lines

from line 115

115115

116116The response is the full vault record:

117117

118```json

118```text wrap

119119{

120120 "type": "vault",

121121 "id": "vlt_01ABC...",

from line 693

693693

694694 The credential's `injection_location` (java, php: `injectionLocation`; csharp, go: `InjectionLocation`) controls which parts of an outbound request the secret is substituted into. It is an optional object, a sibling of `networking` (csharp, go: `Networking`), with two Boolean fields: `header` (csharp, go: `Header`) (request headers) and `body` (csharp, go: `Body`) (request body). `injection_location` (java, php: `injectionLocation`; csharp, go: `InjectionLocation`) is independent of `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) in `networking` (csharp, go: `Networking`): `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) scopes which hosts the secret is substituted for, and `injection_location` (java, php: `injectionLocation`; csharp, go: `InjectionLocation`) scopes which parts of the request it is substituted into.

695695

696 `injection_location` behaves differently on create and on update:

696 `injection_location` (java, php: `injectionLocation`; csharp, go: `InjectionLocation`) behaves differently on create and on update:

697697

698698 | Operation | `injection_location` behavior |

699699 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

from line 708

708708 Credentials created in the Claude Console enable header injection only. If your client sends the secret in the request body, such as a form-encoded token request, the placeholder passes through literally and the service rejects it with its own authentication error. Enable body injection in the Console form when you create the credential, or update the credential with `{"injection_location": {"body": true}}`.

709709 </Note>

710710

711 The substitution happens at egress, not inside the sandbox. Anything that processes the credential locally sees the opaque placeholder, not the real value: clients that validate the credential format at startup might reject it, and clients that compute a request signature from the secret (for example, AWS SigV4) produce an invalid signature. Environment variable credentials work for clients that send the secret value verbatim in an outbound request, in a location the credential's `injection_location` (java, php: `injectionLocation`; csharp, go: `InjectionLocation`) enables.

711 The substitution occurs at egress, not inside the sandbox. Anything that processes the credential locally sees the opaque placeholder, not the real value: clients that validate the credential format at startup might reject it, and clients that compute a request signature from the secret (for example, AWS SigV4) produce an invalid signature. Environment variable credentials work for clients that send the secret value verbatim in an outbound request, in a location the credential's `injection_location` (java, php: `injectionLocation`; csharp, go: `InjectionLocation`) enables.

712712

713713 Substitution is outbound only. If a client uses the stored secret to fetch a session token (for example, an OAuth client-credentials grant), the returned token arrives in the sandbox unredacted. For exchange-based flows, perform the exchange yourself and store the resulting token in the vault instead.

714714

from line 1070

10701070

10711071The response is a `vault_credential_validation` object. `mcp_probe` includes the failed MCP handshake step; `refresh` includes the outcome of the attempted refresh.

10721072

1073```json

1073```text wrap

10741074{

10751075 "type": "vault_credential_validation",

10761076 "credential_id": "vcrd_01ABC...",

managed-agents/workflow-runs Changed · +3 / -3 lines

from line 85

8585

8686The run's first event lists its phases:

8787

88```json

88```text

8989{

9090 "type": "workflow_run.created",

9191 "id": "sevt_01abc...",

from line 106

106106

107107Each phase event names its phase by `workflow_run_phase_id`. That is an `id` in `phases`, but the API doesn't guarantee it:

108108

109```json

109```text wrap

110110{

111111 "type": "workflow_run.phase_started",

112112 "id": "sevt_01def...",

from line 118

118118

119119The run's last event reports how it ended:

120120

121```json

121```text wrap

122122{

123123 "type": "workflow_run.status_ended",

124124 "id": "sevt_01ghi...",

One read of Claude Developer Platformapi-20261022T020713Z

What this read moved