api-20260910T183729Z / documentation capture

api/admin/workspaces/retrieve Page removed · 131 lines, page removed

# Get Workspace ## Path parameters ## Returns ## Example ### Response (200)

The page is gone upstream. What it last said is kept here.

api/admin/workspaces/service_accounts Page removed · 654 lines, page removed

# Service Accounts ## Create Service Account Workspace Member ### Path parameters ### Headers ### Body parameters ### Returns ### Example #### Response (200) ## Get Service Account Workspace Member ### Path parameters ### Headers ### Returns ### Example #### Response (200) ## List Service Account Workspace Members ### Path parameters ### Query parameters ### Headers ### Returns ### Example #### Response (200) ## Update Service Account Workspace Member ### Path parameters ### Headers ### Body parameters ### Returns ### Example #### Response (200) ## Delete Service Account Workspace Member ### Path parameters ### Headers ### Returns ### Example #### Response (200) ## Domain types ### Service Account Create Response ### Service Account Retrieve Response ### Service Account Update Response ### Service Account List Response ### Service Account Delete Response

The page is gone upstream. What it last said is kept here.

api/admin/workspaces/service_accounts/create Page removed · 110 lines, page removed

# Create Service Account Workspace Member ## Path parameters ## Headers ## Body parameters ## Returns ## Example ### Response (200)

The page is gone upstream. What it last said is kept here.

api/admin/workspaces/service_accounts/delete Page removed · 64 lines, page removed

# Delete Service Account Workspace Member ## Path parameters ## Headers ## Returns ## Example ### Response (200)

The page is gone upstream. What it last said is kept here.

api/admin/workspaces/service_accounts/list Page removed · 108 lines, page removed

# List Service Account Workspace Members ## Path parameters ## Query parameters ## Headers ## Returns ## Example ### Response (200)

The page is gone upstream. What it last said is kept here.

api/admin/workspaces/service_accounts/retrieve Page removed · 89 lines, page removed

# Get Service Account Workspace Member ## Path parameters ## Headers ## Returns ## Example ### Response (200)

The page is gone upstream. What it last said is kept here.

api/admin/workspaces/service_accounts/update Page removed · 107 lines, page removed

# Update Service Account Workspace Member ## Path parameters ## Headers ## Body parameters ## Returns ## Example ### Response (200)

The page is gone upstream. What it last said is kept here.

api/admin/workspaces/update Page removed · 194 lines, page removed

# Update Workspace ## Path parameters ## Body parameters ## Returns ## Example ### Response (200)

The page is gone upstream. What it last said is kept here.

api/beta Changed · +33482 / -22540 lines

### Retrieve API Key (Admin API) ## Beta › Organization › Usage Report ### Get Messages Usage Report ### Get Claude Code Usage Report ## Beta › Organization › Cost Report ### Get Cost Report ## Beta › Organization › MCP Tunnels ## Beta › Organization › MCP Tunnels › Tunnel Certificates ## Beta › Organization › Analytics ### Get Activity Summaries ## Beta › Organization › Analytics › Usage ### Get Token Usage Over Time ### Get Per-User Token Usage ## Beta › Organization › Analytics › Cost ### Get Cost Over Time ### Get Per-User Cost ## Beta › Organization › Analytics › Users ### List User Activity ## Beta › Organization › Analytics › Skills ### Get Skill Usage ## Beta › Organization › Analytics › Connectors ### Get Connector Usage ## Beta › Organization › Analytics › Chat Projects ### Get Chat Project Usage ## Beta › Organization › Analytics › Plugins ### Get Plugin Usage ## Beta › Organization › Analytics › Artifacts ### Get Artifact Activity ## Beta › Organization › Spend Limits ### Set Spend Limit ### Get Spend Limit ### Delete Spend Limit ### List Effective Spend Limits ## Beta › Organization › Spend Limits › Increase Requests ### List Spend Limit Increase Requests ### Get Spend Limit Increase Request ### Approve Spend Limit Increase Request ### Deny Spend Limit Increase Request ## Beta › Organization › RBAC Groups ### List RBAC Groups ### Get RBAC Group ### Create RBAC Group ### Update RBAC Group ### Delete RBAC Group ## Beta › Organization › RBAC Groups › Members ### List RBAC Group Members ### Add RBAC Group Member ### Remove RBAC Group Member ## Beta › Organization › RBAC Roles ### List RBAC Roles ### Get RBAC Role ## Beta › Organization › RBAC Roles › Permissions ### List RBAC Role Permissions ### Get API Key

This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.

Nothing in the body moved in this read. What changed is above.

api/beta/agents Changed · +6319 / -5526 lines

### Beta Managed Agents Auto Policy

This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.

Nothing in the body moved in this read. What changed is above.

api/beta/agents/archive Changed · +368 / -313 lines

from line 1

1---

2title: Archive Agent

3url: https://platform.claude.com/docs/en/api/beta/agents/archive

4---

5

16# Archive Agent

27

38**POST** `/v1/agents/{agent_id}/archive`

from line 21

1621

1722 - `string`

1823

19 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`

24 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`

2025

2126 - `"message-batches-2024-09-24"`

2227

from line 69

6469

6570 - `"user-profiles-2026-08-18"`

6671

72 - `"user-profiles-2026-09-04"`

73

6774 - `"advisor-tool-2026-03-01"`

6875

6976 - `"managed-agents-2026-04-01"`

from line 113

106113

107114 - `"mid-conversation-system-clear-at-2026-08-21"`

108115

116- `"anthropic-workspace-id": optional string`

117

109118## Returns

110119

111120- `BetaManagedAgentsAgent object`

from line 121

112121

113122 A Managed Agents `agent`.

114123

124 - `type: "agent"`

125

115126 - `id: string`

116127

117128 - `archived_at: string or null`

from line 141

130141

131142 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

132143

133 - `name: string`

134

135144 - `type: "url"`

136145

146 - `name: string`

147

137148 - `url: string`

138149

139150 - `metadata: map[string]`

from line 273

262273

263274 Resolved coordinator topology with a concrete agent roster.

264275

276 - `type: "coordinator"`

277

265278 - `agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor`

266279

267280 Agents the coordinator may spawn as session threads, each resolved to a specific version.

from line 283

270283

271284 A resolved agent reference with a concrete version.

272285

273 - `id: string`

274

275286 - `type: "agent"`

276287

288 - `id: string`

289

277290 - `version: number`

278291

279292 format: int32

from line 295

282295

283296 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.

284297

298 - `type: "advisor"`

299

285300 - `model: string`

286301

287302 The advisor model id.

288303

289 - `type: "advisor"`

290

291 - `type: "coordinator"`

292

293304 - `name: string`

294305

295306 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

from line 309

298309

299310 A resolved Anthropic-managed skill.

300311

301 - `skill_id: string`

302

303312 - `type: "anthropic"`

304313

314 - `skill_id: string`

315

305316 - `version: string`

306317

307318 - `BetaManagedAgentsCustomSkill object`

from line 319

308319

309320 A resolved user-created custom skill.

310321

311 - `skill_id: string`

312

313322 - `type: "custom"`

314323

324 - `skill_id: string`

325

315326 - `version: string`

316327

317328 - `system: string or null`

from line 331

320331

321332 - `BetaManagedAgentsAgentToolset20260401 object`

322333

334 - `type: "agent_toolset_20260401"`

335

323336 - `configs: array of BetaManagedAgentsAgentToolConfig`

324337

325338 - `BetaManagedAgentsBashToolConfig object`

from line 339

326339

327340 Configuration for the bash tool.

328341

342 - `type: "bash"`

343

329344 - `enabled: boolean`

330345

331346 - `name: "bash"`

332347

333 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

348 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

334349

335350 Permission policy for tool execution.

336351

from line 361

346361

347362 - `type: "always_ask"`

348363

349 - `type: "bash"`

364 - `BetaManagedAgentsAutoPolicy object`

350365

366 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

367

368 - `type: "auto"`

369

351370 - `BetaManagedAgentsEditToolConfig object`

352371

353372 Configuration for the edit tool.

354373

374 - `type: "edit"`

375

355376 - `enabled: boolean`

356377

357378 - `name: "edit"`

358379

359 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

380 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

360381

361382 Permission policy for tool execution.

362383

from line 389

368389

369390 Tool calls require user confirmation before execution.

370391

371 - `type: "edit"`

392 - `BetaManagedAgentsAutoPolicy object`

372393

394 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

395

373396 - `BetaManagedAgentsReadToolConfig object`

374397

375398 Configuration for the read tool.

376399

400 - `type: "read"`

401

377402 - `enabled: boolean`

378403

379404 - `name: "read"`

380405

381 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

406 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

382407

383408 Permission policy for tool execution.

384409

from line 415

390415

391416 Tool calls require user confirmation before execution.

392417

393 - `type: "read"`

418 - `BetaManagedAgentsAutoPolicy object`

394419

420 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

421

395422 - `BetaManagedAgentsWriteToolConfig object`

396423

397424 Configuration for the write tool.

398425

426 - `type: "write"`

427

399428 - `enabled: boolean`

400429

401430 - `name: "write"`

402431

403 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

432 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

404433

405434 Permission policy for tool execution.

406435

from line 441

412441

413442 Tool calls require user confirmation before execution.

414443

415 - `type: "write"`

444 - `BetaManagedAgentsAutoPolicy object`

416445

446 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

447

417448 - `BetaManagedAgentsGlobToolConfig object`

418449

419450 Configuration for the glob tool.

420451

452 - `type: "glob"`

453

421454 - `enabled: boolean`

422455

423456 - `name: "glob"`

424457

425 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

458 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

426459

427460 Permission policy for tool execution.

428461

from line 467

434467

435468 Tool calls require user confirmation before execution.

436469

437 - `type: "glob"`

470 - `BetaManagedAgentsAutoPolicy object`

438471

472 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

473

439474 - `BetaManagedAgentsGrepToolConfig object`

440475

441476 Configuration for the grep tool.

442477

478 - `type: "grep"`

479

443480 - `enabled: boolean`

444481

445482 - `name: "grep"`

446483

447 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

484 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

448485

449486 Permission policy for tool execution.

450487

from line 493

456493

457494 Tool calls require user confirmation before execution.

458495

459 - `type: "grep"`

496 - `BetaManagedAgentsAutoPolicy object`

460497

498 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

499

461500 - `BetaManagedAgentsWebFetchToolConfig object`

462501

463502 Configuration for the web_fetch tool.

464503

504 - `type: "web_fetch"`

505

465506 - `enabled: boolean`

466507

467508 - `name: "web_fetch"`

468509

469 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

510 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

470511

471512 Permission policy for tool execution.

472513

from line 519

478519

479520 Tool calls require user confirmation before execution.

480521

481 - `type: "web_fetch"`

522 - `BetaManagedAgentsAutoPolicy object`

482523

524 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

525

483526 - `allowed_domains: optional array of string`

484527

485528 - `blocked_domains: optional array of string`

from line 535

492535

493536 Configuration for the web_search tool.

494537

538 - `type: "web_search"`

539

495540 - `enabled: boolean`

496541

497542 - `name: "web_search"`

498543

499 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

544 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

500545

501546 Permission policy for tool execution.

502547

from line 553

508553

509554 Tool calls require user confirmation before execution.

510555

511 - `type: "web_search"`

556 - `BetaManagedAgentsAutoPolicy object`

512557

558 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

559

513560 - `allowed_domains: optional array of string`

514561

515562 - `blocked_domains: optional array of string`

from line 597

550597

551598 - `enabled: boolean`

552599

553 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

600 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

554601

555602 Permission policy for tool execution.

556603

from line 609

562609

563610 Tool calls require user confirmation before execution.

564611

565 - `type: "agent_toolset_20260401"`

612 - `BetaManagedAgentsAutoPolicy object`

566613

614 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

615

567616 - `BetaManagedAgentsMCPToolset object`

568617

618 - `type: "mcp_toolset"`

619

569620 - `configs: array of BetaManagedAgentsMCPToolConfig`

570621

571622 - `enabled: boolean`

from line 623

572623

573624 - `name: string`

574625

575 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

626 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

576627

577628 Permission policy for tool execution.

578629

from line 635

584635

585636 Tool calls require user confirmation before execution.

586637

638 - `BetaManagedAgentsAutoPolicy object`

639

640 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

641

587642 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`

588643

589644 Resolved default configuration for all tools from an MCP server.

from line 645

590645

591646 - `enabled: boolean`

592647

593 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

648 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

594649

595650 Permission policy for tool execution.

596651

from line 657

602657

603658 Tool calls require user confirmation before execution.

604659

605 - `mcp_server_name: string`

660 - `BetaManagedAgentsAutoPolicy object`

606661

607 - `type: "mcp_toolset"`

662 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

608663

664 - `mcp_server_name: string`

665

609666 - `BetaManagedAgentsCustomTool object`

610667

611668 A custom tool as returned in API responses.

612669

670 - `type: "custom"`

671

613672 - `description: string`

614673

615674 - `input_schema: BetaManagedAgentsCustomToolInputSchema`

from line 682

623682 - `required: optional array of string or null`

624683

625684 - `name: string`

626

627 - `type: "custom"`

628

629 - `type: "agent"`

630685

631686 - `updated_at: string`

632687

api/beta/agents/create Changed · +994 / -893 lines

from line 1

1---

2title: Create Agent

3url: https://platform.claude.com/docs/en/api/beta/agents/create

4---

5

16# Create Agent

27

38**POST** `/v1/agents`

from line 17

1217

1318 - `string`

1419

15 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`

20 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`

1621

1722 - `"message-batches-2024-09-24"`

1823

from line 65

6065

6166 - `"user-profiles-2026-08-18"`

6267

68 - `"user-profiles-2026-09-04"`

69

6370 - `"advisor-tool-2026-03-01"`

6471

6572 - `"managed-agents-2026-04-01"`

from line 109

102109

103110 - `"mid-conversation-system-clear-at-2026-08-21"`

104111

112- `"anthropic-workspace-id": optional string`

113

105114## Body parameters

106115

107116- `model: BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams`

from line 273

264273

265274 MCP servers this agent connects to. Maximum 20. Names must be unique within the array. Every server must be referenced by an `mcp_toolset` in `tools`; unreferenced servers are rejected. See the [MCP connector guide](https://platform.claude.com/docs/en/managed-agents/mcp-connector).

266275

276 - `type: "url"`

277

267278 - `name: string`

268279

269280 Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.

from line 281

270281

271282 minLength: 1, maxLength: 255

272283

273 - `type: "url"`

274

275284 - `url: string`

276285

277286 Endpoint URL for the MCP server.

from line 295

286295

287296 A coordinator topology: the session's primary thread orchestrates work by spawning session threads, each running an agent drawn from the `agents` roster.

288297

298 - `type: "coordinator"`

299

289300 - `agents: array of BetaManagedAgentsMultiagentRosterEntryParams`

290301

291302 Agents the coordinator may spawn as session threads. 1–20 entries. Each entry is an agent ID string, a versioned `{"type":"agent","id","version"}` reference, or `{"type":"self"}` to allow recursive self-invocation. Entries must reference distinct agents (after resolving `self` and string forms); at most one `self`. Referenced agents must exist, must not be archived, and must not themselves have `multiagent` set (depth limit 1).

from line 307

296307

297308 Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version

298309

310 - `type: "agent"`

311

299312 - `id: string`

300313

301314 The `agent` ID.

from line 315

302315

303316 minLength: 1, maxLength: 128

304317

305 - `type: "agent"`

306

307318 - `version: optional number`

308319

309320 The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.

from line 331

320331

321332 Platform advisor roster entry: a model the session's primary thread may consult mid-turn. At most one per roster; the entry occupies the roster name `anthropic.advisor`.

322333

334 - `type: "advisor"`

335

323336 - `model: string`

324337

325338 A Claude model id. The model must be permitted as an advisor for this agent's model — see the sessions/threads/advisor spec.

from line 339

326339

327340 minLength: 1, maxLength: 256

328341

329 - `type: "advisor"`

330

331 - `type: "coordinator"`

332

333342- `skills: optional array of BetaManagedAgentsSkillParams`

334343

335344 Skills available to the agent.

from line 347

338347

339348 An Anthropic-managed skill.

340349

350 - `type: "anthropic"`

351

341352 - `skill_id: string`

342353

343354 Identifier of the Anthropic skill (e.g., "xlsx").

from line 355

344355

345356 minLength: 1, maxLength: 64

346357

347 - `type: "anthropic"`

348

349358 - `version: optional string or null`

350359

351360 Version to pin. Defaults to latest if omitted.

from line 365

356365

357366 A user-created custom skill.

358367

368 - `type: "custom"`

369

359370 - `skill_id: string`

360371

361372 Tagged ID of the custom skill (e.g., "skill_01XJ5...").

from line 373

362373

363374 minLength: 1, maxLength: 64

364375

365 - `type: "custom"`

366

367376 - `version: optional string or null`

368377

369378 Version to pin. Defaults to latest if omitted.

from line 403

394403

395404 Configuration override for the bash tool.

396405

406 - `type: optional "bash"`

407

397408 - `name: "bash"`

398409

399410 Must be "bash".

from line 413

402413

403414 Whether this tool is enabled and available to Claude. Overrides the default_config setting.

404415

405 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

416 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

406417

407418 Permission policy for tool execution.

408419

from line 429

418429

419430 - `type: "always_ask"`

420431

421 - `type: optional "bash"`

432 - `BetaManagedAgentsAutoPolicy object`

422433

434 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

435

436 - `type: "auto"`

437

423438 - `BetaManagedAgentsEditToolConfigParams object`

424439

425440 Configuration override for the edit tool.

426441

442 - `type: optional "edit"`

443

427444 - `name: "edit"`

428445

429446 Must be "edit".

from line 449

432449

433450 Whether this tool is enabled and available to Claude. Overrides the default_config setting.

434451

435 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

452 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

436453

437454 Permission policy for tool execution.

438455

from line 461

444461

445462 Tool calls require user confirmation before execution.

446463

447 - `type: optional "edit"`

464 - `BetaManagedAgentsAutoPolicy object`

448465

466 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

467

449468 - `BetaManagedAgentsReadToolConfigParams object`

450469

451470 Configuration override for the read tool.

452471

472 - `type: optional "read"`

473

453474 - `name: "read"`

454475

455476 Must be "read".

from line 479

458479

459480 Whether this tool is enabled and available to Claude. Overrides the default_config setting.

460481

461 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

482 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

462483

463484 Permission policy for tool execution.

464485

from line 491

470491

471492 Tool calls require user confirmation before execution.

472493

473 - `type: optional "read"`

494 - `BetaManagedAgentsAutoPolicy object`

474495

496 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

497

475498 - `BetaManagedAgentsWriteToolConfigParams object`

476499

477500 Configuration override for the write tool.

478501

502 - `type: optional "write"`

503

479504 - `name: "write"`

480505

481506 Must be "write".

from line 509

484509

485510 Whether this tool is enabled and available to Claude. Overrides the default_config setting.

486511

487 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

512 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

488513

489514 Permission policy for tool execution.

490515

from line 521

496521

497522 Tool calls require user confirmation before execution.

498523

499 - `type: optional "write"`

524 - `BetaManagedAgentsAutoPolicy object`

500525

526 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

527

501528 - `BetaManagedAgentsGlobToolConfigParams object`

502529

503530 Configuration override for the glob tool.

504531

532 - `type: optional "glob"`

533

505534 - `name: "glob"`

506535

507536 Must be "glob".

from line 539

510539

511540 Whether this tool is enabled and available to Claude. Overrides the default_config setting.

512541

513 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

542 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

514543

515544 Permission policy for tool execution.

516545

from line 551

522551

523552 Tool calls require user confirmation before execution.

524553

525 - `type: optional "glob"`

554 - `BetaManagedAgentsAutoPolicy object`

526555

556 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

557

527558 - `BetaManagedAgentsGrepToolConfigParams object`

528559

529560 Configuration override for the grep tool.

530561

562 - `type: optional "grep"`

563

531564 - `name: "grep"`

532565

533566 Must be "grep".

from line 569

536569

537570 Whether this tool is enabled and available to Claude. Overrides the default_config setting.

538571

539 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

572 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

540573

541574 Permission policy for tool execution.

542575

from line 581

548581

549582 Tool calls require user confirmation before execution.

550583

551 - `type: optional "grep"`

584 - `BetaManagedAgentsAutoPolicy object`

552585

586 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

587

553588 - `BetaManagedAgentsWebFetchToolConfigParams object`

554589

555590 Configuration override for the web_fetch tool.

556591

592 - `type: optional "web_fetch"`

593

557594 - `name: "web_fetch"`

558595

559596 Must be "web_fetch".

from line 613

576613

577614 format: int32

578615

579 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

616 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

580617

581618 Permission policy for tool execution.

582619

from line 625

588625

589626 Tool calls require user confirmation before execution.

590627

591 - `type: optional "web_fetch"`

628 - `BetaManagedAgentsAutoPolicy object`

592629

630 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

631

593632 - `BetaManagedAgentsWebSearchToolConfigParams object`

594633

595634 Configuration override for the web_search tool.

596635

636 - `type: optional "web_search"`

637

597638 - `name: "web_search"`

598639

599640 Must be "web_search".

from line 651

610651

611652 Whether this tool is enabled and available to Claude. Overrides the default_config setting.

612653

613 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

654 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

614655

615656 Permission policy for tool execution.

616657

from line 663

622663

623664 Tool calls require user confirmation before execution.

624665

625 - `type: optional "web_search"`

666 - `BetaManagedAgentsAutoPolicy object`

626667

668 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

669

627670 - `user_location: optional BetaManagedAgentsUserLocation or null`

628671

629672 Approximate user location for search result localization.

from line 705

662705

663706 Whether tools are enabled and available to Claude by default. Defaults to true if not specified.

664707

665 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

708 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

666709

667710 Permission policy for tool execution.

668711

from line 717

674717

675718 Tool calls require user confirmation before execution.

676719

720 - `BetaManagedAgentsAutoPolicy object`

721

722 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

723

677724 - `BetaManagedAgentsMCPToolsetParams object`

678725

679726 Configuration for tools from an MCP server defined in `mcp_servers`.

680727

728 - `type: "mcp_toolset"`

729

681730 - `mcp_server_name: string`

682731

683732 Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.

from line 733

684733

685734 minLength: 1, maxLength: 255

686735

687 - `type: "mcp_toolset"`

688

689736 - `configs: optional array of BetaManagedAgentsMCPToolConfigParams`

690737

691738 Per-tool configuration overrides.

from line 747

700747

701748 Whether this tool is enabled. Overrides the `default_config` setting.

702749

703 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

750 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

704751

705752 Permission policy for tool execution.

706753

from line 759

712759

713760 Tool calls require user confirmation before execution.

714761

762 - `BetaManagedAgentsAutoPolicy object`

763

764 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

765

715766 - `default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or null`

716767

717768 Default configuration for all tools from an MCP server.

from line 771

720771

721772 Whether tools are enabled by default. Defaults to true if not specified.

722773

723 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

774 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

724775

725776 Permission policy for tool execution.

726777

from line 783

732783

733784 Tool calls require user confirmation before execution.

734785

786 - `BetaManagedAgentsAutoPolicy object`

787

788 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

789

735790 - `BetaManagedAgentsCustomToolParams object`

736791

737792 A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event.

738793

794 - `type: "custom"`

795

739796 - `description: string`

740797

741798 Description of what the tool does, shown to the agent to help it decide when to use the tool.

from line 815

758815

759816 minLength: 1, maxLength: 128

760817

761 - `type: "custom"`

762

763818## Returns

764819

765820- `BetaManagedAgentsAgent object`

from line 821

766821

767822 A Managed Agents `agent`.

768823

824 - `type: "agent"`

825

769826 - `id: string`

770827

771828 - `archived_at: string or null`

from line 841

784841

785842 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

786843

787 - `name: string`

788

789844 - `type: "url"`

790845

846 - `name: string`

847

791848 - `url: string`

792849

793850 - `metadata: map[string]`

from line 973

916973

917974 Resolved coordinator topology with a concrete agent roster.

918975

976 - `type: "coordinator"`

977

919978 - `agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor`

920979

921980 Agents the coordinator may spawn as session threads, each resolved to a specific version.

from line 983

924983

925984 A resolved agent reference with a concrete version.

926985

927 - `id: string`

928

929986 - `type: "agent"`

930987

988 - `id: string`

989

931990 - `version: number`

932991

933992 format: int32

from line 995

936995

937996 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.

938997

998 - `type: "advisor"`

999

9391000 - `model: string`

9401001

9411002 The advisor model id.

9421003

943 - `type: "advisor"`

944

945 - `type: "coordinator"`

946

9471004 - `name: string`

9481005

9491006 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

from line 1009

9521009

9531010 A resolved Anthropic-managed skill.

9541011

955 - `skill_id: string`

956

9571012 - `type: "anthropic"`

9581013

1014 - `skill_id: string`

1015

9591016 - `version: string`

9601017

9611018 - `BetaManagedAgentsCustomSkill object`

from line 1019

9621019

9631020 A resolved user-created custom skill.

9641021

965 - `skill_id: string`

966

9671022 - `type: "custom"`

9681023

1024 - `skill_id: string`

1025

9691026 - `version: string`

9701027

9711028 - `system: string or null`

from line 1031

9741031

9751032 - `BetaManagedAgentsAgentToolset20260401 object`

9761033

1034 - `type: "agent_toolset_20260401"`

1035

9771036 - `configs: array of BetaManagedAgentsAgentToolConfig`

9781037

9791038 - `BetaManagedAgentsBashToolConfig object`

from line 1039

9801039

9811040 Configuration for the bash tool.

9821041

1042 - `type: "bash"`

1043

9831044 - `enabled: boolean`

9841045

9851046 - `name: "bash"`

9861047

987 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1048 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

9881049

9891050 Permission policy for tool execution.

9901051

from line 1061

10001061

10011062 - `type: "always_ask"`

10021063

1003 - `type: "bash"`

1064 - `BetaManagedAgentsAutoPolicy object`

10041065

1066 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1067

1068 - `type: "auto"`

1069

10051070 - `BetaManagedAgentsEditToolConfig object`

10061071

10071072 Configuration for the edit tool.

10081073

1074 - `type: "edit"`

1075

10091076 - `enabled: boolean`

10101077

10111078 - `name: "edit"`

10121079

1013 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1080 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

10141081

10151082 Permission policy for tool execution.

10161083

from line 1089

10221089

10231090 Tool calls require user confirmation before execution.

10241091

1025 - `type: "edit"`

1092 - `BetaManagedAgentsAutoPolicy object`

10261093

1094 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1095

10271096 - `BetaManagedAgentsReadToolConfig object`

10281097

10291098 Configuration for the read tool.

10301099

1100 - `type: "read"`

1101

10311102 - `enabled: boolean`

10321103

10331104 - `name: "read"`

10341105

1035 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1106 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

10361107

10371108 Permission policy for tool execution.

10381109

from line 1115

10441115

10451116 Tool calls require user confirmation before execution.

10461117

1047 - `type: "read"`

1118 - `BetaManagedAgentsAutoPolicy object`

10481119

1120 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1121

10491122 - `BetaManagedAgentsWriteToolConfig object`

10501123

10511124 Configuration for the write tool.

10521125

1126 - `type: "write"`

1127

10531128 - `enabled: boolean`

10541129

10551130 - `name: "write"`

10561131

1057 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1132 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

10581133

10591134 Permission policy for tool execution.

10601135

from line 1141

10661141

10671142 Tool calls require user confirmation before execution.

10681143

1069 - `type: "write"`

1144 - `BetaManagedAgentsAutoPolicy object`

10701145

1146 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1147

10711148 - `BetaManagedAgentsGlobToolConfig object`

10721149

10731150 Configuration for the glob tool.

10741151

1152 - `type: "glob"`

1153

10751154 - `enabled: boolean`

10761155

10771156 - `name: "glob"`

10781157

1079 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1158 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

10801159

10811160 Permission policy for tool execution.

10821161

from line 1167

10881167

10891168 Tool calls require user confirmation before execution.

10901169

1091 - `type: "glob"`

1170 - `BetaManagedAgentsAutoPolicy object`

10921171

1172 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1173

10931174 - `BetaManagedAgentsGrepToolConfig object`

10941175

10951176 Configuration for the grep tool.

10961177

1178 - `type: "grep"`

1179

10971180 - `enabled: boolean`

10981181

10991182 - `name: "grep"`

11001183

1101 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1184 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

11021185

11031186 Permission policy for tool execution.

11041187

from line 1193

11101193

11111194 Tool calls require user confirmation before execution.

11121195

1113 - `type: "grep"`

1196 - `BetaManagedAgentsAutoPolicy object`

11141197

1198 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1199

11151200 - `BetaManagedAgentsWebFetchToolConfig object`

11161201

11171202 Configuration for the web_fetch tool.

11181203

1204 - `type: "web_fetch"`

1205

11191206 - `enabled: boolean`

11201207

11211208 - `name: "web_fetch"`

11221209

1123 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1210 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

11241211

11251212 Permission policy for tool execution.

11261213

from line 1219

11321219

11331220 Tool calls require user confirmation before execution.

11341221

1135 - `type: "web_fetch"`

1222 - `BetaManagedAgentsAutoPolicy object`

11361223

1224 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1225

11371226 - `allowed_domains: optional array of string`

11381227

11391228 - `blocked_domains: optional array of string`

from line 1235

11461235

11471236 Configuration for the web_search tool.

11481237

1238 - `type: "web_search"`

1239

11491240 - `enabled: boolean`

11501241

11511242 - `name: "web_search"`

11521243

1153 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1244 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

11541245

11551246 Permission policy for tool execution.

11561247

from line 1253

11621253

11631254 Tool calls require user confirmation before execution.

11641255

1165 - `type: "web_search"`

1256 - `BetaManagedAgentsAutoPolicy object`

11661257

1258 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1259

11671260 - `allowed_domains: optional array of string`

11681261

11691262 - `blocked_domains: optional array of string`

from line 1297

12041297

12051298 - `enabled: boolean`

12061299

1207 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1300 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

12081301

12091302 Permission policy for tool execution.

12101303

from line 1309

12161309

12171310 Tool calls require user confirmation before execution.

12181311

1219 - `type: "agent_toolset_20260401"`

1312 - `BetaManagedAgentsAutoPolicy object`

12201313

1314 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1315

12211316 - `BetaManagedAgentsMCPToolset object`

12221317

1318 - `type: "mcp_toolset"`

1319

12231320 - `configs: array of BetaManagedAgentsMCPToolConfig`

12241321

12251322 - `enabled: boolean`

from line 1323

12261323

12271324 - `name: string`

12281325

1229 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1326 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

12301327

12311328 Permission policy for tool execution.

12321329

from line 1335

12381335

12391336 Tool calls require user confirmation before execution.

12401337

1338 - `BetaManagedAgentsAutoPolicy object`

1339

1340 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1341

12411342 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`

12421343

12431344 Resolved default configuration for all tools from an MCP server.

from line 1345

12441345

12451346 - `enabled: boolean`

12461347

1247 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1348 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

12481349

12491350 Permission policy for tool execution.

12501351

from line 1357

12561357

12571358 Tool calls require user confirmation before execution.

12581359

1259 - `mcp_server_name: string`

1360 - `BetaManagedAgentsAutoPolicy object`

12601361

1261 - `type: "mcp_toolset"`

1362 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

12621363

1364 - `mcp_server_name: string`

1365

12631366 - `BetaManagedAgentsCustomTool object`

12641367

12651368 A custom tool as returned in API responses.

12661369

1370 - `type: "custom"`

1371

12671372 - `description: string`

12681373

12691374 - `input_schema: BetaManagedAgentsCustomToolInputSchema`

from line 1382

12771382 - `required: optional array of string or null`

12781383

12791384 - `name: string`

1280

1281 - `type: "custom"`

1282

1283 - `type: "agent"`

12841385

12851386 - `updated_at: string`

12861387

api/beta/agents/list Changed · +368 / -313 lines

from line 1

1---

2title: List Agents

3url: https://platform.claude.com/docs/en/api/beta/agents/list

4---

5

16# List Agents

27

38**GET** `/v1/agents`

from line 45

4045

4146 - `string`

4247

43 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`

48 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`

4449

4550 - `"message-batches-2024-09-24"`

4651

from line 93

8893

8994 - `"user-profiles-2026-08-18"`

9095

96 - `"user-profiles-2026-09-04"`

97

9198 - `"advisor-tool-2026-03-01"`

9299

93100 - `"managed-agents-2026-04-01"`

from line 137

130137

131138 - `"mid-conversation-system-clear-at-2026-08-21"`

132139

140- `"anthropic-workspace-id": optional string`

141

133142## Returns

134143

135144- `data: array of BetaManagedAgentsAgent`

from line 145

136145

137146 List of agents.

138147

148 - `type: "agent"`

149

139150 - `id: string`

140151

141152 - `archived_at: string or null`

from line 165

154165

155166 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

156167

157 - `name: string`

158

159168 - `type: "url"`

160169

170 - `name: string`

171

161172 - `url: string`

162173

163174 - `metadata: map[string]`

from line 297

286297

287298 Resolved coordinator topology with a concrete agent roster.

288299

300 - `type: "coordinator"`

301

289302 - `agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor`

290303

291304 Agents the coordinator may spawn as session threads, each resolved to a specific version.

from line 307

294307

295308 A resolved agent reference with a concrete version.

296309

297 - `id: string`

298

299310 - `type: "agent"`

300311

312 - `id: string`

313

301314 - `version: number`

302315

303316 format: int32

from line 319

306319

307320 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.

308321

322 - `type: "advisor"`

323

309324 - `model: string`

310325

311326 The advisor model id.

312327

313 - `type: "advisor"`

314

315 - `type: "coordinator"`

316

317328 - `name: string`

318329

319330 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

from line 333

322333

323334 A resolved Anthropic-managed skill.

324335

325 - `skill_id: string`

326

327336 - `type: "anthropic"`

328337

338 - `skill_id: string`

339

329340 - `version: string`

330341

331342 - `BetaManagedAgentsCustomSkill object`

from line 343

332343

333344 A resolved user-created custom skill.

334345

335 - `skill_id: string`

336

337346 - `type: "custom"`

338347

348 - `skill_id: string`

349

339350 - `version: string`

340351

341352 - `system: string or null`

from line 355

344355

345356 - `BetaManagedAgentsAgentToolset20260401 object`

346357

358 - `type: "agent_toolset_20260401"`

359

347360 - `configs: array of BetaManagedAgentsAgentToolConfig`

348361

349362 - `BetaManagedAgentsBashToolConfig object`

from line 363

350363

351364 Configuration for the bash tool.

352365

366 - `type: "bash"`

367

353368 - `enabled: boolean`

354369

355370 - `name: "bash"`

356371

357 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

372 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

358373

359374 Permission policy for tool execution.

360375

from line 385

370385

371386 - `type: "always_ask"`

372387

373 - `type: "bash"`

388 - `BetaManagedAgentsAutoPolicy object`

374389

390 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

391

392 - `type: "auto"`

393

375394 - `BetaManagedAgentsEditToolConfig object`

376395

377396 Configuration for the edit tool.

378397

398 - `type: "edit"`

399

379400 - `enabled: boolean`

380401

381402 - `name: "edit"`

382403

383 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

404 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

384405

385406 Permission policy for tool execution.

386407

from line 413

392413

393414 Tool calls require user confirmation before execution.

394415

395 - `type: "edit"`

416 - `BetaManagedAgentsAutoPolicy object`

396417

418 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

419

397420 - `BetaManagedAgentsReadToolConfig object`

398421

399422 Configuration for the read tool.

400423

424 - `type: "read"`

425

401426 - `enabled: boolean`

402427

403428 - `name: "read"`

404429

405 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

430 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

406431

407432 Permission policy for tool execution.

408433

from line 439

414439

415440 Tool calls require user confirmation before execution.

416441

417 - `type: "read"`

442 - `BetaManagedAgentsAutoPolicy object`

418443

444 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

445

419446 - `BetaManagedAgentsWriteToolConfig object`

420447

421448 Configuration for the write tool.

422449

450 - `type: "write"`

451

423452 - `enabled: boolean`

424453

425454 - `name: "write"`

426455

427 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

456 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

428457

429458 Permission policy for tool execution.

430459

from line 465

436465

437466 Tool calls require user confirmation before execution.

438467

439 - `type: "write"`

468 - `BetaManagedAgentsAutoPolicy object`

440469

470 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

471

441472 - `BetaManagedAgentsGlobToolConfig object`

442473

443474 Configuration for the glob tool.

444475

476 - `type: "glob"`

477

445478 - `enabled: boolean`

446479

447480 - `name: "glob"`

448481

449 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

482 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

450483

451484 Permission policy for tool execution.

452485

from line 491

458491

459492 Tool calls require user confirmation before execution.

460493

461 - `type: "glob"`

494 - `BetaManagedAgentsAutoPolicy object`

462495

496 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

497

463498 - `BetaManagedAgentsGrepToolConfig object`

464499

465500 Configuration for the grep tool.

466501

502 - `type: "grep"`

503

467504 - `enabled: boolean`

468505

469506 - `name: "grep"`

470507

471 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

508 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

472509

473510 Permission policy for tool execution.

474511

from line 517

480517

481518 Tool calls require user confirmation before execution.

482519

483 - `type: "grep"`

520 - `BetaManagedAgentsAutoPolicy object`

484521

522 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

523

485524 - `BetaManagedAgentsWebFetchToolConfig object`

486525

487526 Configuration for the web_fetch tool.

488527

528 - `type: "web_fetch"`

529

489530 - `enabled: boolean`

490531

491532 - `name: "web_fetch"`

492533

493 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

534 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

494535

495536 Permission policy for tool execution.

496537

from line 543

502543

503544 Tool calls require user confirmation before execution.

504545

505 - `type: "web_fetch"`

546 - `BetaManagedAgentsAutoPolicy object`

506547

548 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

549

507550 - `allowed_domains: optional array of string`

508551

509552 - `blocked_domains: optional array of string`

from line 559

516559

517560 Configuration for the web_search tool.

518561

562 - `type: "web_search"`

563

519564 - `enabled: boolean`

520565

521566 - `name: "web_search"`

522567

523 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

568 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

524569

525570 Permission policy for tool execution.

526571

from line 577

532577

533578 Tool calls require user confirmation before execution.

534579

535 - `type: "web_search"`

580 - `BetaManagedAgentsAutoPolicy object`

536581

582 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

583

537584 - `allowed_domains: optional array of string`

538585

539586 - `blocked_domains: optional array of string`

from line 621

574621

575622 - `enabled: boolean`

576623

577 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

624 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

578625

579626 Permission policy for tool execution.

580627

from line 633

586633

587634 Tool calls require user confirmation before execution.

588635

589 - `type: "agent_toolset_20260401"`

636 - `BetaManagedAgentsAutoPolicy object`

590637

638 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

639

591640 - `BetaManagedAgentsMCPToolset object`

592641

642 - `type: "mcp_toolset"`

643

593644 - `configs: array of BetaManagedAgentsMCPToolConfig`

594645

595646 - `enabled: boolean`

from line 647

596647

597648 - `name: string`

598649

599 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

650 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

600651

601652 Permission policy for tool execution.

602653

from line 659

608659

609660 Tool calls require user confirmation before execution.

610661

662 - `BetaManagedAgentsAutoPolicy object`

663

664 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

665

611666 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`

612667

613668 Resolved default configuration for all tools from an MCP server.

from line 669

614669

615670 - `enabled: boolean`

616671

617 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

672 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

618673

619674 Permission policy for tool execution.

620675

from line 681

626681

627682 Tool calls require user confirmation before execution.

628683

629 - `mcp_server_name: string`

684 - `BetaManagedAgentsAutoPolicy object`

630685

631 - `type: "mcp_toolset"`

686 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

632687

688 - `mcp_server_name: string`

689

633690 - `BetaManagedAgentsCustomTool object`

634691

635692 A custom tool as returned in API responses.

636693

694 - `type: "custom"`

695

637696 - `description: string`

638697

639698 - `input_schema: BetaManagedAgentsCustomToolInputSchema`

from line 706

647706 - `required: optional array of string or null`

648707

649708 - `name: string`

650

651 - `type: "custom"`

652

653 - `type: "agent"`

654709

655710 - `updated_at: string`

656711

api/beta/agents/retrieve Changed · +368 / -313 lines

from line 1

1---

2title: Get Agent

3url: https://platform.claude.com/docs/en/api/beta/agents/retrieve

4---

5

16# Get Agent

27

38**GET** `/v1/agents/{agent_id}`

from line 29

2429

2530 - `string`

2631

27 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`

32 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`

2833

2934 - `"message-batches-2024-09-24"`

3035

from line 77

7277

7378 - `"user-profiles-2026-08-18"`

7479

80 - `"user-profiles-2026-09-04"`

81

7582 - `"advisor-tool-2026-03-01"`

7683

7784 - `"managed-agents-2026-04-01"`

from line 121

114121

115122 - `"mid-conversation-system-clear-at-2026-08-21"`

116123

124- `"anthropic-workspace-id": optional string`

125

117126## Returns

118127

119128- `BetaManagedAgentsAgent object`

from line 129

120129

121130 A Managed Agents `agent`.

122131

132 - `type: "agent"`

133

123134 - `id: string`

124135

125136 - `archived_at: string or null`

from line 149

138149

139150 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

140151

141 - `name: string`

142

143152 - `type: "url"`

144153

154 - `name: string`

155

145156 - `url: string`

146157

147158 - `metadata: map[string]`

from line 281

270281

271282 Resolved coordinator topology with a concrete agent roster.

272283

284 - `type: "coordinator"`

285

273286 - `agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor`

274287

275288 Agents the coordinator may spawn as session threads, each resolved to a specific version.

from line 291

278291

279292 A resolved agent reference with a concrete version.

280293

281 - `id: string`

282

283294 - `type: "agent"`

284295

296 - `id: string`

297

285298 - `version: number`

286299

287300 format: int32

from line 303

290303

291304 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.

292305

306 - `type: "advisor"`

307

293308 - `model: string`

294309

295310 The advisor model id.

296311

297 - `type: "advisor"`

298

299 - `type: "coordinator"`

300

301312 - `name: string`

302313

303314 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

from line 317

306317

307318 A resolved Anthropic-managed skill.

308319

309 - `skill_id: string`

310

311320 - `type: "anthropic"`

312321

322 - `skill_id: string`

323

313324 - `version: string`

314325

315326 - `BetaManagedAgentsCustomSkill object`

from line 327

316327

317328 A resolved user-created custom skill.

318329

319 - `skill_id: string`

320

321330 - `type: "custom"`

322331

332 - `skill_id: string`

333

323334 - `version: string`

324335

325336 - `system: string or null`

from line 339

328339

329340 - `BetaManagedAgentsAgentToolset20260401 object`

330341

342 - `type: "agent_toolset_20260401"`

343

331344 - `configs: array of BetaManagedAgentsAgentToolConfig`

332345

333346 - `BetaManagedAgentsBashToolConfig object`

from line 347

334347

335348 Configuration for the bash tool.

336349

350 - `type: "bash"`

351

337352 - `enabled: boolean`

338353

339354 - `name: "bash"`

340355

341 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

356 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

342357

343358 Permission policy for tool execution.

344359

from line 369

354369

355370 - `type: "always_ask"`

356371

357 - `type: "bash"`

372 - `BetaManagedAgentsAutoPolicy object`

358373

374 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

375

376 - `type: "auto"`

377

359378 - `BetaManagedAgentsEditToolConfig object`

360379

361380 Configuration for the edit tool.

362381

382 - `type: "edit"`

383

363384 - `enabled: boolean`

364385

365386 - `name: "edit"`

366387

367 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

388 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

368389

369390 Permission policy for tool execution.

370391

from line 397

376397

377398 Tool calls require user confirmation before execution.

378399

379 - `type: "edit"`

400 - `BetaManagedAgentsAutoPolicy object`

380401

402 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

403

381404 - `BetaManagedAgentsReadToolConfig object`

382405

383406 Configuration for the read tool.

384407

408 - `type: "read"`

409

385410 - `enabled: boolean`

386411

387412 - `name: "read"`

388413

389 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

414 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

390415

391416 Permission policy for tool execution.

392417

from line 423

398423

399424 Tool calls require user confirmation before execution.

400425

401 - `type: "read"`

426 - `BetaManagedAgentsAutoPolicy object`

402427

428 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

429

403430 - `BetaManagedAgentsWriteToolConfig object`

404431

405432 Configuration for the write tool.

406433

434 - `type: "write"`

435

407436 - `enabled: boolean`

408437

409438 - `name: "write"`

410439

411 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

440 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

412441

413442 Permission policy for tool execution.

414443

from line 449

420449

421450 Tool calls require user confirmation before execution.

422451

423 - `type: "write"`

452 - `BetaManagedAgentsAutoPolicy object`

424453

454 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

455

425456 - `BetaManagedAgentsGlobToolConfig object`

426457

427458 Configuration for the glob tool.

428459

460 - `type: "glob"`

461

429462 - `enabled: boolean`

430463

431464 - `name: "glob"`

432465

433 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

466 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

434467

435468 Permission policy for tool execution.

436469

from line 475

442475

443476 Tool calls require user confirmation before execution.

444477

445 - `type: "glob"`

478 - `BetaManagedAgentsAutoPolicy object`

446479

480 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

481

447482 - `BetaManagedAgentsGrepToolConfig object`

448483

449484 Configuration for the grep tool.

450485

486 - `type: "grep"`

487

451488 - `enabled: boolean`

452489

453490 - `name: "grep"`

454491

455 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

492 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

456493

457494 Permission policy for tool execution.

458495

from line 501

464501

465502 Tool calls require user confirmation before execution.

466503

467 - `type: "grep"`

504 - `BetaManagedAgentsAutoPolicy object`

468505

506 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

507

469508 - `BetaManagedAgentsWebFetchToolConfig object`

470509

471510 Configuration for the web_fetch tool.

472511

512 - `type: "web_fetch"`

513

473514 - `enabled: boolean`

474515

475516 - `name: "web_fetch"`

476517

477 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

518 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

478519

479520 Permission policy for tool execution.

480521

from line 527

486527

487528 Tool calls require user confirmation before execution.

488529

489 - `type: "web_fetch"`

530 - `BetaManagedAgentsAutoPolicy object`

490531

532 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

533

491534 - `allowed_domains: optional array of string`

492535

493536 - `blocked_domains: optional array of string`

from line 543

500543

501544 Configuration for the web_search tool.

502545

546 - `type: "web_search"`

547

503548 - `enabled: boolean`

504549

505550 - `name: "web_search"`

506551

507 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

552 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

508553

509554 Permission policy for tool execution.

510555

from line 561

516561

517562 Tool calls require user confirmation before execution.

518563

519 - `type: "web_search"`

564 - `BetaManagedAgentsAutoPolicy object`

520565

566 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

567

521568 - `allowed_domains: optional array of string`

522569

523570 - `blocked_domains: optional array of string`

from line 605

558605

559606 - `enabled: boolean`

560607

561 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

608 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

562609

563610 Permission policy for tool execution.

564611

from line 617

570617

571618 Tool calls require user confirmation before execution.

572619

573 - `type: "agent_toolset_20260401"`

620 - `BetaManagedAgentsAutoPolicy object`

574621

622 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

623

575624 - `BetaManagedAgentsMCPToolset object`

576625

626 - `type: "mcp_toolset"`

627

577628 - `configs: array of BetaManagedAgentsMCPToolConfig`

578629

579630 - `enabled: boolean`

from line 631

580631

581632 - `name: string`

582633

583 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

634 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

584635

585636 Permission policy for tool execution.

586637

from line 643

592643

593644 Tool calls require user confirmation before execution.

594645

646 - `BetaManagedAgentsAutoPolicy object`

647

648 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

649

595650 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`

596651

597652 Resolved default configuration for all tools from an MCP server.

from line 653

598653

599654 - `enabled: boolean`

600655

601 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

656 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

602657

603658 Permission policy for tool execution.

604659

from line 665

610665

611666 Tool calls require user confirmation before execution.

612667

613 - `mcp_server_name: string`

668 - `BetaManagedAgentsAutoPolicy object`

614669

615 - `type: "mcp_toolset"`

670 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

616671

672 - `mcp_server_name: string`

673

617674 - `BetaManagedAgentsCustomTool object`

618675

619676 A custom tool as returned in API responses.

620677

678 - `type: "custom"`

679

621680 - `description: string`

622681

623682 - `input_schema: BetaManagedAgentsCustomToolInputSchema`

from line 690

631690 - `required: optional array of string or null`

632691

633692 - `name: string`

634

635 - `type: "custom"`

636

637 - `type: "agent"`

638693

639694 - `updated_at: string`

640695

api/beta/agents/update Changed · +1000 / -899 lines

from line 1

1---

2title: Update Agent

3url: https://platform.claude.com/docs/en/api/beta/agents/update

4---

5

16# Update Agent

27

38**POST** `/v1/agents/{agent_id}`

from line 21

1621

1722 - `string`

1823

19 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`

24 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`

2025

2126 - `"message-batches-2024-09-24"`

2227

from line 69

6469

6570 - `"user-profiles-2026-08-18"`

6671

72 - `"user-profiles-2026-09-04"`

73

6774 - `"advisor-tool-2026-03-01"`

6875

6976 - `"managed-agents-2026-04-01"`

from line 113

106113

107114 - `"mid-conversation-system-clear-at-2026-08-21"`

108115

116- `"anthropic-workspace-id": optional string`

117

109118## Body parameters

110119

111120- `description: optional string or null`

from line 127

118127

119128 MCP servers. Full replacement. Omit to preserve; send empty array or `null` to clear. Names must be unique. Maximum 20. Every server must be referenced by an `mcp_toolset` in the agent's resulting `tools`; unreferenced servers are rejected. See the [MCP connector guide](https://platform.claude.com/docs/en/managed-agents/mcp-connector).

120129

130 - `type: "url"`

131

121132 - `name: string`

122133

123134 Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.

from line 135

124135

125136 minLength: 1, maxLength: 255

126137

127 - `type: "url"`

128

129138 - `url: string`

130139

131140 Endpoint URL for the MCP server.

from line 293

284293

285294 A coordinator topology: the session's primary thread orchestrates work by spawning session threads, each running an agent drawn from the `agents` roster.

286295

296 - `type: "coordinator"`

297

287298 - `agents: array of BetaManagedAgentsMultiagentRosterEntryParams`

288299

289300 Agents the coordinator may spawn as session threads. 1–20 entries. Each entry is an agent ID string, a versioned `{"type":"agent","id","version"}` reference, or `{"type":"self"}` to allow recursive self-invocation. Entries must reference distinct agents (after resolving `self` and string forms); at most one `self`. Referenced agents must exist, must not be archived, and must not themselves have `multiagent` set (depth limit 1).

from line 305

294305

295306 Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version

296307

308 - `type: "agent"`

309

297310 - `id: string`

298311

299312 The `agent` ID.

from line 313

300313

301314 minLength: 1, maxLength: 128

302315

303 - `type: "agent"`

304

305316 - `version: optional number`

306317

307318 The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.

from line 329

318329

319330 Platform advisor roster entry: a model the session's primary thread may consult mid-turn. At most one per roster; the entry occupies the roster name `anthropic.advisor`.

320331

332 - `type: "advisor"`

333

321334 - `model: string`

322335

323336 A Claude model id. The model must be permitted as an advisor for this agent's model — see the sessions/threads/advisor spec.

from line 337

324337

325338 minLength: 1, maxLength: 256

326339

327 - `type: "advisor"`

328

329 - `type: "coordinator"`

330

331340- `name: optional string`

332341

333342 Human-readable name. Must be non-empty. Omit to preserve. Cannot be cleared.

from line 351

342351

343352 An Anthropic-managed skill.

344353

354 - `type: "anthropic"`

355

345356 - `skill_id: string`

346357

347358 Identifier of the Anthropic skill (e.g., "xlsx").

from line 359

348359

349360 minLength: 1, maxLength: 64

350361

351 - `type: "anthropic"`

352

353362 - `version: optional string or null`

354363

355364 Version to pin. Defaults to latest if omitted.

from line 369

360369

361370 A user-created custom skill.

362371

372 - `type: "custom"`

373

363374 - `skill_id: string`

364375

365376 Tagged ID of the custom skill (e.g., "skill_01XJ5...").

from line 377

366377

367378 minLength: 1, maxLength: 64

368379

369 - `type: "custom"`

370

371380 - `version: optional string or null`

372381

373382 Version to pin. Defaults to latest if omitted.

from line 407

398407

399408 Configuration override for the bash tool.

400409

410 - `type: optional "bash"`

411

401412 - `name: "bash"`

402413

403414 Must be "bash".

from line 417

406417

407418 Whether this tool is enabled and available to Claude. Overrides the default_config setting.

408419

409 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

420 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

410421

411422 Permission policy for tool execution.

412423

from line 433

422433

423434 - `type: "always_ask"`

424435

425 - `type: optional "bash"`

436 - `BetaManagedAgentsAutoPolicy object`

426437

438 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

439

440 - `type: "auto"`

441

427442 - `BetaManagedAgentsEditToolConfigParams object`

428443

429444 Configuration override for the edit tool.

430445

446 - `type: optional "edit"`

447

431448 - `name: "edit"`

432449

433450 Must be "edit".

from line 453

436453

437454 Whether this tool is enabled and available to Claude. Overrides the default_config setting.

438455

439 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

456 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

440457

441458 Permission policy for tool execution.

442459

from line 465

448465

449466 Tool calls require user confirmation before execution.

450467

451 - `type: optional "edit"`

468 - `BetaManagedAgentsAutoPolicy object`

452469

470 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

471

453472 - `BetaManagedAgentsReadToolConfigParams object`

454473

455474 Configuration override for the read tool.

456475

476 - `type: optional "read"`

477

457478 - `name: "read"`

458479

459480 Must be "read".

from line 483

462483

463484 Whether this tool is enabled and available to Claude. Overrides the default_config setting.

464485

465 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

486 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

466487

467488 Permission policy for tool execution.

468489

from line 495

474495

475496 Tool calls require user confirmation before execution.

476497

477 - `type: optional "read"`

498 - `BetaManagedAgentsAutoPolicy object`

478499

500 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

501

479502 - `BetaManagedAgentsWriteToolConfigParams object`

480503

481504 Configuration override for the write tool.

482505

506 - `type: optional "write"`

507

483508 - `name: "write"`

484509

485510 Must be "write".

from line 513

488513

489514 Whether this tool is enabled and available to Claude. Overrides the default_config setting.

490515

491 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

516 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

492517

493518 Permission policy for tool execution.

494519

from line 525

500525

501526 Tool calls require user confirmation before execution.

502527

503 - `type: optional "write"`

528 - `BetaManagedAgentsAutoPolicy object`

504529

530 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

531

505532 - `BetaManagedAgentsGlobToolConfigParams object`

506533

507534 Configuration override for the glob tool.

508535

536 - `type: optional "glob"`

537

509538 - `name: "glob"`

510539

511540 Must be "glob".

from line 543

514543

515544 Whether this tool is enabled and available to Claude. Overrides the default_config setting.

516545

517 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

546 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

518547

519548 Permission policy for tool execution.

520549

from line 555

526555

527556 Tool calls require user confirmation before execution.

528557

529 - `type: optional "glob"`

558 - `BetaManagedAgentsAutoPolicy object`

530559

560 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

561

531562 - `BetaManagedAgentsGrepToolConfigParams object`

532563

533564 Configuration override for the grep tool.

534565

566 - `type: optional "grep"`

567

535568 - `name: "grep"`

536569

537570 Must be "grep".

from line 573

540573

541574 Whether this tool is enabled and available to Claude. Overrides the default_config setting.

542575

543 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

576 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

544577

545578 Permission policy for tool execution.

546579

from line 585

552585

553586 Tool calls require user confirmation before execution.

554587

555 - `type: optional "grep"`

588 - `BetaManagedAgentsAutoPolicy object`

556589

590 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

591

557592 - `BetaManagedAgentsWebFetchToolConfigParams object`

558593

559594 Configuration override for the web_fetch tool.

560595

596 - `type: optional "web_fetch"`

597

561598 - `name: "web_fetch"`

562599

563600 Must be "web_fetch".

from line 617

580617

581618 format: int32

582619

583 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

620 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

584621

585622 Permission policy for tool execution.

586623

from line 629

592629

593630 Tool calls require user confirmation before execution.

594631

595 - `type: optional "web_fetch"`

632 - `BetaManagedAgentsAutoPolicy object`

596633

634 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

635

597636 - `BetaManagedAgentsWebSearchToolConfigParams object`

598637

599638 Configuration override for the web_search tool.

600639

640 - `type: optional "web_search"`

641

601642 - `name: "web_search"`

602643

603644 Must be "web_search".

from line 655

614655

615656 Whether this tool is enabled and available to Claude. Overrides the default_config setting.

616657

617 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

658 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

618659

619660 Permission policy for tool execution.

620661

from line 667

626667

627668 Tool calls require user confirmation before execution.

628669

629 - `type: optional "web_search"`

670 - `BetaManagedAgentsAutoPolicy object`

630671

672 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

673

631674 - `user_location: optional BetaManagedAgentsUserLocation or null`

632675

633676 Approximate user location for search result localization.

from line 709

666709

667710 Whether tools are enabled and available to Claude by default. Defaults to true if not specified.

668711

669 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

712 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

670713

671714 Permission policy for tool execution.

672715

from line 721

678721

679722 Tool calls require user confirmation before execution.

680723

724 - `BetaManagedAgentsAutoPolicy object`

725

726 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

727

681728 - `BetaManagedAgentsMCPToolsetParams object`

682729

683730 Configuration for tools from an MCP server defined in `mcp_servers`.

684731

732 - `type: "mcp_toolset"`

733

685734 - `mcp_server_name: string`

686735

687736 Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.

from line 737

688737

689738 minLength: 1, maxLength: 255

690739

691 - `type: "mcp_toolset"`

692

693740 - `configs: optional array of BetaManagedAgentsMCPToolConfigParams`

694741

695742 Per-tool configuration overrides.

from line 751

704751

705752 Whether this tool is enabled. Overrides the `default_config` setting.

706753

707 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

754 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

708755

709756 Permission policy for tool execution.

710757

from line 763

716763

717764 Tool calls require user confirmation before execution.

718765

766 - `BetaManagedAgentsAutoPolicy object`

767

768 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

769

719770 - `default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or null`

720771

721772 Default configuration for all tools from an MCP server.

from line 775

724775

725776 Whether tools are enabled by default. Defaults to true if not specified.

726777

727 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`

778 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`

728779

729780 Permission policy for tool execution.

730781

from line 787

736787

737788 Tool calls require user confirmation before execution.

738789

790 - `BetaManagedAgentsAutoPolicy object`

791

792 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

793

739794 - `BetaManagedAgentsCustomToolParams object`

740795

741796 A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event.

742797

798 - `type: "custom"`

799

743800 - `description: string`

744801

745802 Description of what the tool does, shown to the agent to help it decide when to use the tool.

from line 819

762819

763820 minLength: 1, maxLength: 128

764821

765 - `type: "custom"`

766

767822- `version: optional number`

768823

769824 The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. Must be at least 1 if specified. When supplied, the request fails if it does not match the server's current version; omit to apply the update unconditionally.

from line 831

776831

777832 A Managed Agents `agent`.

778833

834 - `type: "agent"`

835

779836 - `id: string`

780837

781838 - `archived_at: string or null`

from line 851

794851

795852 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

796853

797 - `name: string`

798

799854 - `type: "url"`

800855

856 - `name: string`

857

801858 - `url: string`

802859

803860 - `metadata: map[string]`

from line 983

926983

927984 Resolved coordinator topology with a concrete agent roster.

928985

986 - `type: "coordinator"`

987

929988 - `agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor`

930989

931990 Agents the coordinator may spawn as session threads, each resolved to a specific version.

from line 993

934993

935994 A resolved agent reference with a concrete version.

936995

937 - `id: string`

938

939996 - `type: "agent"`

940997

998 - `id: string`

999

9411000 - `version: number`

9421001

9431002 format: int32

from line 1005

9461005

9471006 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.

9481007

1008 - `type: "advisor"`

1009

9491010 - `model: string`

9501011

9511012 The advisor model id.

9521013

953 - `type: "advisor"`

954

955 - `type: "coordinator"`

956

9571014 - `name: string`

9581015

9591016 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

from line 1019

9621019

9631020 A resolved Anthropic-managed skill.

9641021

965 - `skill_id: string`

966

9671022 - `type: "anthropic"`

9681023

1024 - `skill_id: string`

1025

9691026 - `version: string`

9701027

9711028 - `BetaManagedAgentsCustomSkill object`

from line 1029

9721029

9731030 A resolved user-created custom skill.

9741031

975 - `skill_id: string`

976

9771032 - `type: "custom"`

9781033

1034 - `skill_id: string`

1035

9791036 - `version: string`

9801037

9811038 - `system: string or null`

from line 1041

9841041

9851042 - `BetaManagedAgentsAgentToolset20260401 object`

9861043

1044 - `type: "agent_toolset_20260401"`

1045

9871046 - `configs: array of BetaManagedAgentsAgentToolConfig`

9881047

9891048 - `BetaManagedAgentsBashToolConfig object`

from line 1049

9901049

9911050 Configuration for the bash tool.

9921051

1052 - `type: "bash"`

1053

9931054 - `enabled: boolean`

9941055

9951056 - `name: "bash"`

9961057

997 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1058 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

9981059

9991060 Permission policy for tool execution.

10001061

from line 1071

10101071

10111072 - `type: "always_ask"`

10121073

1013 - `type: "bash"`

1074 - `BetaManagedAgentsAutoPolicy object`

10141075

1076 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1077

1078 - `type: "auto"`

1079

10151080 - `BetaManagedAgentsEditToolConfig object`

10161081

10171082 Configuration for the edit tool.

10181083

1084 - `type: "edit"`

1085

10191086 - `enabled: boolean`

10201087

10211088 - `name: "edit"`

10221089

1023 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1090 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

10241091

10251092 Permission policy for tool execution.

10261093

from line 1099

10321099

10331100 Tool calls require user confirmation before execution.

10341101

1035 - `type: "edit"`

1102 - `BetaManagedAgentsAutoPolicy object`

10361103

1104 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1105

10371106 - `BetaManagedAgentsReadToolConfig object`

10381107

10391108 Configuration for the read tool.

10401109

1110 - `type: "read"`

1111

10411112 - `enabled: boolean`

10421113

10431114 - `name: "read"`

10441115

1045 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1116 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

10461117

10471118 Permission policy for tool execution.

10481119

from line 1125

10541125

10551126 Tool calls require user confirmation before execution.

10561127

1057 - `type: "read"`

1128 - `BetaManagedAgentsAutoPolicy object`

10581129

1130 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1131

10591132 - `BetaManagedAgentsWriteToolConfig object`

10601133

10611134 Configuration for the write tool.

10621135

1136 - `type: "write"`

1137

10631138 - `enabled: boolean`

10641139

10651140 - `name: "write"`

10661141

1067 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1142 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

10681143

10691144 Permission policy for tool execution.

10701145

from line 1151

10761151

10771152 Tool calls require user confirmation before execution.

10781153

1079 - `type: "write"`

1154 - `BetaManagedAgentsAutoPolicy object`

10801155

1156 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1157

10811158 - `BetaManagedAgentsGlobToolConfig object`

10821159

10831160 Configuration for the glob tool.

10841161

1162 - `type: "glob"`

1163

10851164 - `enabled: boolean`

10861165

10871166 - `name: "glob"`

10881167

1089 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1168 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

10901169

10911170 Permission policy for tool execution.

10921171

from line 1177

10981177

10991178 Tool calls require user confirmation before execution.

11001179

1101 - `type: "glob"`

1180 - `BetaManagedAgentsAutoPolicy object`

11021181

1182 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1183

11031184 - `BetaManagedAgentsGrepToolConfig object`

11041185

11051186 Configuration for the grep tool.

11061187

1188 - `type: "grep"`

1189

11071190 - `enabled: boolean`

11081191

11091192 - `name: "grep"`

11101193

1111 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1194 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

11121195

11131196 Permission policy for tool execution.

11141197

from line 1203

11201203

11211204 Tool calls require user confirmation before execution.

11221205

1123 - `type: "grep"`

1206 - `BetaManagedAgentsAutoPolicy object`

11241207

1208 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1209

11251210 - `BetaManagedAgentsWebFetchToolConfig object`

11261211

11271212 Configuration for the web_fetch tool.

11281213

1214 - `type: "web_fetch"`

1215

11291216 - `enabled: boolean`

11301217

11311218 - `name: "web_fetch"`

11321219

1133 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1220 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

11341221

11351222 Permission policy for tool execution.

11361223

from line 1229

11421229

11431230 Tool calls require user confirmation before execution.

11441231

1145 - `type: "web_fetch"`

1232 - `BetaManagedAgentsAutoPolicy object`

11461233

1234 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1235

11471236 - `allowed_domains: optional array of string`

11481237

11491238 - `blocked_domains: optional array of string`

from line 1245

11561245

11571246 Configuration for the web_search tool.

11581247

1248 - `type: "web_search"`

1249

11591250 - `enabled: boolean`

11601251

11611252 - `name: "web_search"`

11621253

1163 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1254 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

11641255

11651256 Permission policy for tool execution.

11661257

from line 1263

11721263

11731264 Tool calls require user confirmation before execution.

11741265

1175 - `type: "web_search"`

1266 - `BetaManagedAgentsAutoPolicy object`

11761267

1268 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1269

11771270 - `allowed_domains: optional array of string`

11781271

11791272 - `blocked_domains: optional array of string`

from line 1307

12141307

12151308 - `enabled: boolean`

12161309

1217 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1310 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

12181311

12191312 Permission policy for tool execution.

12201313

from line 1319

12261319

12271320 Tool calls require user confirmation before execution.

12281321

1229 - `type: "agent_toolset_20260401"`

1322 - `BetaManagedAgentsAutoPolicy object`

12301323

1324 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1325

12311326 - `BetaManagedAgentsMCPToolset object`

12321327

1328 - `type: "mcp_toolset"`

1329

12331330 - `configs: array of BetaManagedAgentsMCPToolConfig`

12341331

12351332 - `enabled: boolean`

from line 1333

12361333

12371334 - `name: string`

12381335

1239 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1336 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

12401337

12411338 Permission policy for tool execution.

12421339

from line 1345

12481345

12491346 Tool calls require user confirmation before execution.

12501347

1348 - `BetaManagedAgentsAutoPolicy object`

1349

1350 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1351

12511352 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`

12521353

12531354 Resolved default configuration for all tools from an MCP server.

from line 1355

12541355

12551356 - `enabled: boolean`

12561357

1257 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1358 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

12581359

12591360 Permission policy for tool execution.

12601361

from line 1367

12661367

12671368 Tool calls require user confirmation before execution.

12681369

1269 - `mcp_server_name: string`

1370 - `BetaManagedAgentsAutoPolicy object`

12701371

1271 - `type: "mcp_toolset"`

1372 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

12721373

1374 - `mcp_server_name: string`

1375

12731376 - `BetaManagedAgentsCustomTool object`

12741377

12751378 A custom tool as returned in API responses.

12761379

1380 - `type: "custom"`

1381

12771382 - `description: string`

12781383

12791384 - `input_schema: BetaManagedAgentsCustomToolInputSchema`

from line 1392

12871392 - `required: optional array of string or null`

12881393

12891394 - `name: string`

1290

1291 - `type: "custom"`

1292

1293 - `type: "agent"`

12941395

12951396 - `updated_at: string`

12961397

api/beta/agents/versions Changed · +368 / -313 lines

from line 1

1---

2title: Versions

3url: https://platform.claude.com/docs/en/api/beta/agents/versions

4---

5

16# Versions

27

38## List Agent Versions

from line 35

3035

3136 - `string`

3237

33 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`

38 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`

3439

3540 - `"message-batches-2024-09-24"`

3641

from line 83

7883

7984 - `"user-profiles-2026-08-18"`

8085

86 - `"user-profiles-2026-09-04"`

87

8188 - `"advisor-tool-2026-03-01"`

8289

8390 - `"managed-agents-2026-04-01"`

from line 127

120127

121128 - `"mid-conversation-system-clear-at-2026-08-21"`

122129

130- `"anthropic-workspace-id": optional string`

131

123132### Returns

124133

125134- `data: array of BetaManagedAgentsAgent`

from line 135

126135

127136 Agent versions.

128137

138 - `type: "agent"`

139

129140 - `id: string`

130141

131142 - `archived_at: string or null`

from line 155

144155

145156 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

146157

147 - `name: string`

148

149158 - `type: "url"`

150159

160 - `name: string`

161

151162 - `url: string`

152163

153164 - `metadata: map[string]`

from line 287

276287

277288 Resolved coordinator topology with a concrete agent roster.

278289

290 - `type: "coordinator"`

291

279292 - `agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor`

280293

281294 Agents the coordinator may spawn as session threads, each resolved to a specific version.

from line 297

284297

285298 A resolved agent reference with a concrete version.

286299

287 - `id: string`

288

289300 - `type: "agent"`

290301

302 - `id: string`

303

291304 - `version: number`

292305

293306 format: int32

from line 309

296309

297310 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.

298311

312 - `type: "advisor"`

313

299314 - `model: string`

300315

301316 The advisor model id.

302317

303 - `type: "advisor"`

304

305 - `type: "coordinator"`

306

307318 - `name: string`

308319

309320 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

from line 323

312323

313324 A resolved Anthropic-managed skill.

314325

315 - `skill_id: string`

316

317326 - `type: "anthropic"`

318327

328 - `skill_id: string`

329

319330 - `version: string`

320331

321332 - `BetaManagedAgentsCustomSkill object`

from line 333

322333

323334 A resolved user-created custom skill.

324335

325 - `skill_id: string`

326

327336 - `type: "custom"`

328337

338 - `skill_id: string`

339

329340 - `version: string`

330341

331342 - `system: string or null`

from line 345

334345

335346 - `BetaManagedAgentsAgentToolset20260401 object`

336347

348 - `type: "agent_toolset_20260401"`

349

337350 - `configs: array of BetaManagedAgentsAgentToolConfig`

338351

339352 - `BetaManagedAgentsBashToolConfig object`

from line 353

340353

341354 Configuration for the bash tool.

342355

356 - `type: "bash"`

357

343358 - `enabled: boolean`

344359

345360 - `name: "bash"`

346361

347 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

362 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

348363

349364 Permission policy for tool execution.

350365

from line 375

360375

361376 - `type: "always_ask"`

362377

363 - `type: "bash"`

378 - `BetaManagedAgentsAutoPolicy object`

364379

380 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

381

382 - `type: "auto"`

383

365384 - `BetaManagedAgentsEditToolConfig object`

366385

367386 Configuration for the edit tool.

368387

388 - `type: "edit"`

389

369390 - `enabled: boolean`

370391

371392 - `name: "edit"`

372393

373 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

394 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

374395

375396 Permission policy for tool execution.

376397

from line 403

382403

383404 Tool calls require user confirmation before execution.

384405

385 - `type: "edit"`

406 - `BetaManagedAgentsAutoPolicy object`

386407

408 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

409

387410 - `BetaManagedAgentsReadToolConfig object`

388411

389412 Configuration for the read tool.

390413

414 - `type: "read"`

415

391416 - `enabled: boolean`

392417

393418 - `name: "read"`

394419

395 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

420 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

396421

397422 Permission policy for tool execution.

398423

from line 429

404429

405430 Tool calls require user confirmation before execution.

406431

407 - `type: "read"`

432 - `BetaManagedAgentsAutoPolicy object`

408433

434 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

435

409436 - `BetaManagedAgentsWriteToolConfig object`

410437

411438 Configuration for the write tool.

412439

440 - `type: "write"`

441

413442 - `enabled: boolean`

414443

415444 - `name: "write"`

416445

417 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

446 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

418447

419448 Permission policy for tool execution.

420449

from line 455

426455

427456 Tool calls require user confirmation before execution.

428457

429 - `type: "write"`

458 - `BetaManagedAgentsAutoPolicy object`

430459

460 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

461

431462 - `BetaManagedAgentsGlobToolConfig object`

432463

433464 Configuration for the glob tool.

434465

466 - `type: "glob"`

467

435468 - `enabled: boolean`

436469

437470 - `name: "glob"`

438471

439 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

472 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

440473

441474 Permission policy for tool execution.

442475

from line 481

448481

449482 Tool calls require user confirmation before execution.

450483

451 - `type: "glob"`

484 - `BetaManagedAgentsAutoPolicy object`

452485

486 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

487

453488 - `BetaManagedAgentsGrepToolConfig object`

454489

455490 Configuration for the grep tool.

456491

492 - `type: "grep"`

493

457494 - `enabled: boolean`

458495

459496 - `name: "grep"`

460497

461 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

498 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

462499

463500 Permission policy for tool execution.

464501

from line 507

470507

471508 Tool calls require user confirmation before execution.

472509

473 - `type: "grep"`

510 - `BetaManagedAgentsAutoPolicy object`

474511

512 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

513

475514 - `BetaManagedAgentsWebFetchToolConfig object`

476515

477516 Configuration for the web_fetch tool.

478517

518 - `type: "web_fetch"`

519

479520 - `enabled: boolean`

480521

481522 - `name: "web_fetch"`

482523

483 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

524 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

484525

485526 Permission policy for tool execution.

486527

from line 533

492533

493534 Tool calls require user confirmation before execution.

494535

495 - `type: "web_fetch"`

536 - `BetaManagedAgentsAutoPolicy object`

496537

538 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

539

497540 - `allowed_domains: optional array of string`

498541

499542 - `blocked_domains: optional array of string`

from line 549

506549

507550 Configuration for the web_search tool.

508551

552 - `type: "web_search"`

553

509554 - `enabled: boolean`

510555

511556 - `name: "web_search"`

512557

513 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

558 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

514559

515560 Permission policy for tool execution.

516561

from line 567

522567

523568 Tool calls require user confirmation before execution.

524569

525 - `type: "web_search"`

570 - `BetaManagedAgentsAutoPolicy object`

526571

572 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

573

527574 - `allowed_domains: optional array of string`

528575

529576 - `blocked_domains: optional array of string`

from line 611

564611

565612 - `enabled: boolean`

566613

567 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

614 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

568615

569616 Permission policy for tool execution.

570617

from line 623

576623

577624 Tool calls require user confirmation before execution.

578625

579 - `type: "agent_toolset_20260401"`

626 - `BetaManagedAgentsAutoPolicy object`

580627

628 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

629

581630 - `BetaManagedAgentsMCPToolset object`

582631

632 - `type: "mcp_toolset"`

633

583634 - `configs: array of BetaManagedAgentsMCPToolConfig`

584635

585636 - `enabled: boolean`

from line 637

586637

587638 - `name: string`

588639

589 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

640 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

590641

591642 Permission policy for tool execution.

592643

from line 649

598649

599650 Tool calls require user confirmation before execution.

600651

652 - `BetaManagedAgentsAutoPolicy object`

653

654 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

655

601656 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`

602657

603658 Resolved default configuration for all tools from an MCP server.

from line 659

604659

605660 - `enabled: boolean`

606661

607 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

662 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

608663

609664 Permission policy for tool execution.

610665

from line 671

616671

617672 Tool calls require user confirmation before execution.

618673

619 - `mcp_server_name: string`

674 - `BetaManagedAgentsAutoPolicy object`

620675

621 - `type: "mcp_toolset"`

676 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

622677

678 - `mcp_server_name: string`

679

623680 - `BetaManagedAgentsCustomTool object`

624681

625682 A custom tool as returned in API responses.

626683

684 - `type: "custom"`

685

627686 - `description: string`

628687

629688 - `input_schema: BetaManagedAgentsCustomToolInputSchema`

from line 696

637696 - `required: optional array of string or null`

638697

639698 - `name: string`

640

641 - `type: "custom"`

642

643 - `type: "agent"`

644699

645700 - `updated_at: string`

646701

api/beta/agents/versions/list Changed · +368 / -313 lines

from line 1

1---

2title: List Agent Versions

3url: https://platform.claude.com/docs/en/api/beta/agents/versions/list

4---

5

16# List Agent Versions

27

38**GET** `/v1/agents/{agent_id}/versions`

from line 33

2833

2934 - `string`

3035

31 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`

36 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`

3237

3338 - `"message-batches-2024-09-24"`

3439

from line 81

7681

7782 - `"user-profiles-2026-08-18"`

7883

84 - `"user-profiles-2026-09-04"`

85

7986 - `"advisor-tool-2026-03-01"`

8087

8188 - `"managed-agents-2026-04-01"`

from line 125

118125

119126 - `"mid-conversation-system-clear-at-2026-08-21"`

120127

128- `"anthropic-workspace-id": optional string`

129

121130## Returns

122131

123132- `data: array of BetaManagedAgentsAgent`

from line 133

124133

125134 Agent versions.

126135

136 - `type: "agent"`

137

127138 - `id: string`

128139

129140 - `archived_at: string or null`

from line 153

142153

143154 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

144155

145 - `name: string`

146

147156 - `type: "url"`

148157

158 - `name: string`

159

149160 - `url: string`

150161

151162 - `metadata: map[string]`

from line 285

274285

275286 Resolved coordinator topology with a concrete agent roster.

276287

288 - `type: "coordinator"`

289

277290 - `agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor`

278291

279292 Agents the coordinator may spawn as session threads, each resolved to a specific version.

from line 295

282295

283296 A resolved agent reference with a concrete version.

284297

285 - `id: string`

286

287298 - `type: "agent"`

288299

300 - `id: string`

301

289302 - `version: number`

290303

291304 format: int32

from line 307

294307

295308 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.

296309

310 - `type: "advisor"`

311

297312 - `model: string`

298313

299314 The advisor model id.

300315

301 - `type: "advisor"`

302

303 - `type: "coordinator"`

304

305316 - `name: string`

306317

307318 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

from line 321

310321

311322 A resolved Anthropic-managed skill.

312323

313 - `skill_id: string`

314

315324 - `type: "anthropic"`

316325

326 - `skill_id: string`

327

317328 - `version: string`

318329

319330 - `BetaManagedAgentsCustomSkill object`

from line 331

320331

321332 A resolved user-created custom skill.

322333

323 - `skill_id: string`

324

325334 - `type: "custom"`

326335

336 - `skill_id: string`

337

327338 - `version: string`

328339

329340 - `system: string or null`

from line 343

332343

333344 - `BetaManagedAgentsAgentToolset20260401 object`

334345

346 - `type: "agent_toolset_20260401"`

347

335348 - `configs: array of BetaManagedAgentsAgentToolConfig`

336349

337350 - `BetaManagedAgentsBashToolConfig object`

from line 351

338351

339352 Configuration for the bash tool.

340353

354 - `type: "bash"`

355

341356 - `enabled: boolean`

342357

343358 - `name: "bash"`

344359

345 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

360 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

346361

347362 Permission policy for tool execution.

348363

from line 373

358373

359374 - `type: "always_ask"`

360375

361 - `type: "bash"`

376 - `BetaManagedAgentsAutoPolicy object`

362377

378 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

379

380 - `type: "auto"`

381

363382 - `BetaManagedAgentsEditToolConfig object`

364383

365384 Configuration for the edit tool.

366385

386 - `type: "edit"`

387

367388 - `enabled: boolean`

368389

369390 - `name: "edit"`

370391

371 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

392 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

372393

373394 Permission policy for tool execution.

374395

from line 401

380401

381402 Tool calls require user confirmation before execution.

382403

383 - `type: "edit"`

404 - `BetaManagedAgentsAutoPolicy object`

384405

406 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

407

385408 - `BetaManagedAgentsReadToolConfig object`

386409

387410 Configuration for the read tool.

388411

412 - `type: "read"`

413

389414 - `enabled: boolean`

390415

391416 - `name: "read"`

392417

393 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

418 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

394419

395420 Permission policy for tool execution.

396421

from line 427

402427

403428 Tool calls require user confirmation before execution.

404429

405 - `type: "read"`

430 - `BetaManagedAgentsAutoPolicy object`

406431

432 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

433

407434 - `BetaManagedAgentsWriteToolConfig object`

408435

409436 Configuration for the write tool.

410437

438 - `type: "write"`

439

411440 - `enabled: boolean`

412441

413442 - `name: "write"`

414443

415 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

444 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

416445

417446 Permission policy for tool execution.

418447

from line 453

424453

425454 Tool calls require user confirmation before execution.

426455

427 - `type: "write"`

456 - `BetaManagedAgentsAutoPolicy object`

428457

458 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

459

429460 - `BetaManagedAgentsGlobToolConfig object`

430461

431462 Configuration for the glob tool.

432463

464 - `type: "glob"`

465

433466 - `enabled: boolean`

434467

435468 - `name: "glob"`

436469

437 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

470 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

438471

439472 Permission policy for tool execution.

440473

from line 479

446479

447480 Tool calls require user confirmation before execution.

448481

449 - `type: "glob"`

482 - `BetaManagedAgentsAutoPolicy object`

450483

484 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

485

451486 - `BetaManagedAgentsGrepToolConfig object`

452487

453488 Configuration for the grep tool.

454489

490 - `type: "grep"`

491

455492 - `enabled: boolean`

456493

457494 - `name: "grep"`

458495

459 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

496 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

460497

461498 Permission policy for tool execution.

462499

from line 505

468505

469506 Tool calls require user confirmation before execution.

470507

471 - `type: "grep"`

508 - `BetaManagedAgentsAutoPolicy object`

472509

510 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

511

473512 - `BetaManagedAgentsWebFetchToolConfig object`

474513

475514 Configuration for the web_fetch tool.

476515

516 - `type: "web_fetch"`

517

477518 - `enabled: boolean`

478519

479520 - `name: "web_fetch"`

480521

481 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

522 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

482523

483524 Permission policy for tool execution.

484525

from line 531

490531

491532 Tool calls require user confirmation before execution.

492533

493 - `type: "web_fetch"`

534 - `BetaManagedAgentsAutoPolicy object`

494535

536 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

537

495538 - `allowed_domains: optional array of string`

496539

497540 - `blocked_domains: optional array of string`

from line 547

504547

505548 Configuration for the web_search tool.

506549

550 - `type: "web_search"`

551

507552 - `enabled: boolean`

508553

509554 - `name: "web_search"`

510555

511 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

556 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

512557

513558 Permission policy for tool execution.

514559

from line 565

520565

521566 Tool calls require user confirmation before execution.

522567

523 - `type: "web_search"`

568 - `BetaManagedAgentsAutoPolicy object`

524569

570 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

571

525572 - `allowed_domains: optional array of string`

526573

527574 - `blocked_domains: optional array of string`

from line 609

562609

563610 - `enabled: boolean`

564611

565 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

612 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

566613

567614 Permission policy for tool execution.

568615

from line 621

574621

575622 Tool calls require user confirmation before execution.

576623

577 - `type: "agent_toolset_20260401"`

624 - `BetaManagedAgentsAutoPolicy object`

578625

626 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

627

579628 - `BetaManagedAgentsMCPToolset object`

580629

630 - `type: "mcp_toolset"`

631

581632 - `configs: array of BetaManagedAgentsMCPToolConfig`

582633

583634 - `enabled: boolean`

from line 635

584635

585636 - `name: string`

586637

587 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

638 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

588639

589640 Permission policy for tool execution.

590641

from line 647

596647

597648 Tool calls require user confirmation before execution.

598649

650 - `BetaManagedAgentsAutoPolicy object`

651

652 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

653

599654 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`

600655

601656 Resolved default configuration for all tools from an MCP server.

from line 657

602657

603658 - `enabled: boolean`

604659

605 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

660 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

606661

607662 Permission policy for tool execution.

608663

from line 669

614669

615670 Tool calls require user confirmation before execution.

616671

617 - `mcp_server_name: string`

672 - `BetaManagedAgentsAutoPolicy object`

618673

619 - `type: "mcp_toolset"`

674 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

620675

676 - `mcp_server_name: string`

677

621678 - `BetaManagedAgentsCustomTool object`

622679

623680 A custom tool as returned in API responses.

624681

682 - `type: "custom"`

683

625684 - `description: string`

626685

627686 - `input_schema: BetaManagedAgentsCustomToolInputSchema`

from line 694

635694 - `required: optional array of string or null`

636695

637696 - `name: string`

638

639 - `type: "custom"`

640

641 - `type: "agent"`

642697

643698 - `updated_at: string`

644699

api/beta/deployment_runs Changed · +293 / -280 lines

from line 1

1---

2title: Deployment Runs

3url: https://platform.claude.com/docs/en/api/beta/deployment_runs

4---

5

16# Deployment Runs

27

38## List Deployment Runs

from line 71

6671

6772 - `string`

6873

69 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`

74 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`

7075

7176 - `"message-batches-2024-09-24"`

7277

from line 119

114119

115120 - `"user-profiles-2026-08-18"`

116121

122 - `"user-profiles-2026-09-04"`

123

117124 - `"advisor-tool-2026-03-01"`

118125

119126 - `"managed-agents-2026-04-01"`

from line 163

156163

157164 - `"mid-conversation-system-clear-at-2026-08-21"`

158165

166- `"anthropic-workspace-id": optional string`

167

159168### Returns

160169

161170- `data: array of BetaManagedAgentsDeploymentRun`

from line 171

162171

163172 List of deployment runs.

164173

174 - `type: "deployment_run"`

175

165176 - `id: string`

166177

167178 Unique identifier for this run (`drun_...`).

from line 181

170181

171182 A resolved agent reference with a concrete version.

172183

173 - `id: string`

174

175184 - `type: "agent"`

176185

186 - `id: string`

187

177188 - `version: number`

178189

179190 format: int32

from line 207

196207

197208 The deployment's environment was archived.

198209

210 - `type: "environment_archived_error"`

211

199212 - `message: string`

200213

201214 Human-readable error description.

202215

203 - `type: "environment_archived_error"`

204

205216 - `BetaManagedAgentsAgentArchivedRunError object`

206217

207218 The deployment's agent was archived.

208219

220 - `type: "agent_archived_error"`

221

209222 - `message: string`

210223

211224 Human-readable error description.

212225

213 - `type: "agent_archived_error"`

214

215226 - `BetaManagedAgentsEnvironmentNotFoundRunError object`

216227

217228 The deployment's environment no longer exists.

218229

230 - `type: "environment_not_found_error"`

231

219232 - `message: string`

220233

221234 Human-readable error description.

222235

223 - `type: "environment_not_found_error"`

224

225236 - `BetaManagedAgentsVaultNotFoundRunError object`

226237

227238 A vault referenced by the deployment no longer exists.

228239

240 - `type: "vault_not_found_error"`

241

229242 - `message: string`

230243

231244 Human-readable error description.

232245

233 - `type: "vault_not_found_error"`

234

235246 - `BetaManagedAgentsVaultArchivedRunError object`

236247

237248 A vault referenced by the deployment is archived.

238249

250 - `type: "vault_archived_error"`

251

239252 - `message: string`

240253

241254 Human-readable error description.

242255

243 - `type: "vault_archived_error"`

244

245256 - `BetaManagedAgentsFileNotFoundRunError object`

246257

247258 A file resource referenced by the deployment no longer exists.

248259

260 - `type: "file_not_found_error"`

261

249262 - `message: string`

250263

251264 Human-readable error description.

252265

253 - `type: "file_not_found_error"`

254

255266 - `BetaManagedAgentsMemoryStoreArchivedRunError object`

256267

257268 A memory store referenced by the deployment is archived.

258269

270 - `type: "memory_store_archived_error"`

271

259272 - `message: string`

260273

261274 Human-readable error description.

262275

263 - `type: "memory_store_archived_error"`

264

265276 - `BetaManagedAgentsSkillNotFoundRunError object`

266277

267278 A skill referenced by the deployment's agent no longer exists.

268279

280 - `type: "skill_not_found_error"`

281

269282 - `message: string`

270283

271284 Human-readable error description.

272285

273 - `type: "skill_not_found_error"`

274

275286 - `BetaManagedAgentsSessionResourceNotFoundRunError object`

276287

277288 A referenced resource no longer exists and its kind was not reported.

278289

290 - `type: "session_resource_not_found_error"`

291

279292 - `message: string`

280293

281294 Human-readable error description.

282295

283 - `type: "session_resource_not_found_error"`

284

285296 - `BetaManagedAgentsWorkspaceArchivedRunError object`

286297

287298 The deployment's workspace was archived.

288299

300 - `type: "workspace_archived_error"`

301

289302 - `message: string`

290303

291304 Human-readable error description.

292305

293 - `type: "workspace_archived_error"`

294

295306 - `BetaManagedAgentsOrganizationDisabledRunError object`

296307

297308 The deployment's organization is disabled.

298309

310 - `type: "organization_disabled_error"`

311

299312 - `message: string`

300313

301314 Human-readable error description.

302315

303 - `type: "organization_disabled_error"`

304

305316 - `BetaManagedAgentsSessionRateLimitedRunError object`

306317

307318 Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed.

308319

320 - `type: "session_rate_limited_error"`

321

309322 - `message: string`

310323

311324 Human-readable error description.

312325

313 - `type: "session_rate_limited_error"`

314

315326 - `BetaManagedAgentsSessionCreationRejectedRunError object`

316327

317328 The session create request was rejected with a non-retryable validation error.

318329

330 - `type: "session_creation_rejected_error"`

331

319332 - `message: string`

320333

321334 Human-readable error description.

322335

323 - `type: "session_creation_rejected_error"`

324

325336 - `BetaManagedAgentsUnknownRunError object`

326337

327338 An unknown or unexpected error caused the run to fail. A fallback variant; clients that do not recognize a new error type can match on message alone.

328339

340 - `type: "unknown_error"`

341

329342 - `message: string`

330343

331344 Human-readable error description.

332345

333 - `type: "unknown_error"`

334

335346 - `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object`

336347

337348 The deployment configures resources, but its environment is self-hosted and cannot mount them.

338349

350 - `type: "self_hosted_resources_unsupported_error"`

351

339352 - `message: string`

340353

341354 Human-readable error description.

342355

343 - `type: "self_hosted_resources_unsupported_error"`

344

345356 - `BetaManagedAgentsMCPEgressBlockedRunError object`

346357

347358 An MCP server host used by the deployment's agent is blocked by the environment's network policy.

348359

360 - `type: "mcp_egress_blocked_error"`

361

349362 - `message: string`

350363

351364 Human-readable error description.

352365

353 - `type: "mcp_egress_blocked_error"`

354

355366 - `session_id: string or null`

356367

357368 Populated on success. Null on creation failure. Exactly one of `session_id` or `error` is non-null.

from line 375

364375

365376 The run was fired by the deployment's cron schedule.

366377

378 - `type: "schedule"`

379

367380 - `scheduled_at: string`

368381

369382 A timestamp in RFC 3339 format

from line 383

370383

371384 format: date-time

372385

373 - `type: "schedule"`

374

375386 - `BetaManagedAgentsManualTriggerContext object`

376387

377388 The run was started manually by creating a session directly against the deployment.

from line 389

378389

379390 - `type: "manual"`

380391

381 - `type: "deployment_run"`

382

383392- `next_page: optional string or null`

384393

385394 Opaque cursor for the next page. Null when no more results.

from line 450

441450

442451 - `string`

443452

444 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`

453 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`

445454

446455 - `"message-batches-2024-09-24"`

447456

from line 498

489498

490499 - `"user-profiles-2026-08-18"`

491500

501 - `"user-profiles-2026-09-04"`

502

492503 - `"advisor-tool-2026-03-01"`

493504

494505 - `"managed-agents-2026-04-01"`

from line 542

531542

532543 - `"mid-conversation-system-clear-at-2026-08-21"`

533544

545- `"anthropic-workspace-id": optional string`

546

534547### Returns

535548

536549- `BetaManagedAgentsDeploymentRun object`

from line 550

537550

538551 A persistent, append-only record of a single deployment execution. Records session creation success or failure — no session lifecycle tracking.

539552

553 - `type: "deployment_run"`

554

540555 - `id: string`

541556

542557 Unique identifier for this run (`drun_...`).

from line 560

545560

546561 A resolved agent reference with a concrete version.

547562

548 - `id: string`

549

550563 - `type: "agent"`

551564

565 - `id: string`

566

552567 - `version: number`

553568

554569 format: int32

from line 586

571586

572587 The deployment's environment was archived.

573588

589 - `type: "environment_archived_error"`

590

574591 - `message: string`

575592

576593 Human-readable error description.

577594

578 - `type: "environment_archived_error"`

579

580595 - `BetaManagedAgentsAgentArchivedRunError object`

581596

582597 The deployment's agent was archived.

583598

599 - `type: "agent_archived_error"`

600

584601 - `message: string`

585602

586603 Human-readable error description.

587604

588 - `type: "agent_archived_error"`

589

590605 - `BetaManagedAgentsEnvironmentNotFoundRunError object`

591606

592607 The deployment's environment no longer exists.

593608

609 - `type: "environment_not_found_error"`

610

594611 - `message: string`

595612

596613 Human-readable error description.

597614

598 - `type: "environment_not_found_error"`

599

600615 - `BetaManagedAgentsVaultNotFoundRunError object`

601616

602617 A vault referenced by the deployment no longer exists.

603618

619 - `type: "vault_not_found_error"`

620

604621 - `message: string`

605622

606623 Human-readable error description.

607624

608 - `type: "vault_not_found_error"`

609

610625 - `BetaManagedAgentsVaultArchivedRunError object`

611626

612627 A vault referenced by the deployment is archived.

613628

629 - `type: "vault_archived_error"`

630

614631 - `message: string`

615632

616633 Human-readable error description.

617634

618 - `type: "vault_archived_error"`

619

620635 - `BetaManagedAgentsFileNotFoundRunError object`

621636

622637 A file resource referenced by the deployment no longer exists.

623638

639 - `type: "file_not_found_error"`

640

624641 - `message: string`

625642

626643 Human-readable error description.

627644

628 - `type: "file_not_found_error"`

629

630645 - `BetaManagedAgentsMemoryStoreArchivedRunError object`

631646

632647 A memory store referenced by the deployment is archived.

633648

649 - `type: "memory_store_archived_error"`

650

634651 - `message: string`

635652

636653 Human-readable error description.

637654

638 - `type: "memory_store_archived_error"`

639

640655 - `BetaManagedAgentsSkillNotFoundRunError object`

641656

642657 A skill referenced by the deployment's agent no longer exists.

643658

659 - `type: "skill_not_found_error"`

660

644661 - `message: string`

645662

646663 Human-readable error description.

647664

648 - `type: "skill_not_found_error"`

649

650665 - `BetaManagedAgentsSessionResourceNotFoundRunError object`

651666

652667 A referenced resource no longer exists and its kind was not reported.

653668

669 - `type: "session_resource_not_found_error"`

670

654671 - `message: string`

655672

656673 Human-readable error description.

657674

658 - `type: "session_resource_not_found_error"`

659

660675 - `BetaManagedAgentsWorkspaceArchivedRunError object`

661676

662677 The deployment's workspace was archived.

663678

679 - `type: "workspace_archived_error"`

680

664681 - `message: string`

665682

666683 Human-readable error description.

667684

668 - `type: "workspace_archived_error"`

669

670685 - `BetaManagedAgentsOrganizationDisabledRunError object`

671686

672687 The deployment's organization is disabled.

673688

689 - `type: "organization_disabled_error"`

690

674691 - `message: string`

675692

676693 Human-readable error description.

677694

678 - `type: "organization_disabled_error"`

679

680695 - `BetaManagedAgentsSessionRateLimitedRunError object`

681696

682697 Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed.

683698

699 - `type: "session_rate_limited_error"`

700

684701 - `message: string`

685702

686703 Human-readable error description.

687704

688 - `type: "session_rate_limited_error"`

689

690705 - `BetaManagedAgentsSessionCreationRejectedRunError object`

691706

692707 The session create request was rejected with a non-retryable validation error.

693708

709 - `type: "session_creation_rejected_error"`

710

694711 - `message: string`

695712

696713 Human-readable error description.

697714

698 - `type: "session_creation_rejected_error"`

699

700715 - `BetaManagedAgentsUnknownRunError object`

701716

702717 An unknown or unexpected error caused the run to fail. A fallback variant; clients that do not recognize a new error type can match on message alone.

703718

719 - `type: "unknown_error"`

720

704721 - `message: string`

705722

706723 Human-readable error description.

707724

708 - `type: "unknown_error"`

709

710725 - `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object`

711726

712727 The deployment configures resources, but its environment is self-hosted and cannot mount them.

713728

729 - `type: "self_hosted_resources_unsupported_error"`

730

714731 - `message: string`

715732

716733 Human-readable error description.

717734

718 - `type: "self_hosted_resources_unsupported_error"`

719

720735 - `BetaManagedAgentsMCPEgressBlockedRunError object`

721736

722737 An MCP server host used by the deployment's agent is blocked by the environment's network policy.

723738

739 - `type: "mcp_egress_blocked_error"`

740

724741 - `message: string`

725742

726743 Human-readable error description.

727744

728 - `type: "mcp_egress_blocked_error"`

729

730745 - `session_id: string or null`

731746

732747 Populated on success. Null on creation failure. Exactly one of `session_id` or `error` is non-null.

from line 754

739754

740755 The run was fired by the deployment's cron schedule.

741756

757 - `type: "schedule"`

758

742759 - `scheduled_at: string`

743760

744761 A timestamp in RFC 3339 format

from line 762

745762

746763 format: date-time

747764

748 - `type: "schedule"`

749

750765 - `BetaManagedAgentsManualTriggerContext object`

751766

752767 The run was started manually by creating a session directly against the deployment.

from line 768

753768

754769 - `type: "manual"`

755770

756 - `type: "deployment_run"`

757

758771### Example

759772

760773```bash

from line 810

797810

798811 The deployment's agent was archived.

799812

813 - `type: "agent_archived_error"`

814

800815 - `message: string`

801816

802817 Human-readable error description.

803818

804 - `type: "agent_archived_error"`

805

806819### Beta Managed Agents Deployment Run

807820

808821- `BetaManagedAgentsDeploymentRun object`

from line 822

809822

810823 A persistent, append-only record of a single deployment execution. Records session creation success or failure — no session lifecycle tracking.

811824

825 - `type: "deployment_run"`

826

812827 - `id: string`

813828

814829 Unique identifier for this run (`drun_...`).

from line 832

817832

818833 A resolved agent reference with a concrete version.

819834

820 - `id: string`

821

822835 - `type: "agent"`

823836

837 - `id: string`

838

824839 - `version: number`

825840

826841 format: int32

from line 858

843858

844859 The deployment's environment was archived.

845860

861 - `type: "environment_archived_error"`

862

846863 - `message: string`

847864

848865 Human-readable error description.

849866

850 - `type: "environment_archived_error"`

851

852867 - `BetaManagedAgentsAgentArchivedRunError object`

853868

854869 The deployment's agent was archived.

855870

871 - `type: "agent_archived_error"`

872

856873 - `message: string`

857874

858875 Human-readable error description.

859876

860 - `type: "agent_archived_error"`

861

862877 - `BetaManagedAgentsEnvironmentNotFoundRunError object`

863878

864879 The deployment's environment no longer exists.

865880

881 - `type: "environment_not_found_error"`

882

866883 - `message: string`

867884

868885 Human-readable error description.

869886

870 - `type: "environment_not_found_error"`

871

872887 - `BetaManagedAgentsVaultNotFoundRunError object`

873888

874889 A vault referenced by the deployment no longer exists.

875890

891 - `type: "vault_not_found_error"`

892

876893 - `message: string`

877894

878895 Human-readable error description.

879896

880 - `type: "vault_not_found_error"`

881

882897 - `BetaManagedAgentsVaultArchivedRunError object`

883898

884899 A vault referenced by the deployment is archived.

885900

901 - `type: "vault_archived_error"`

902

886903 - `message: string`

887904

888905 Human-readable error description.

889906

890 - `type: "vault_archived_error"`

891

892907 - `BetaManagedAgentsFileNotFoundRunError object`

893908

894909 A file resource referenced by the deployment no longer exists.

895910

911 - `type: "file_not_found_error"`

912

896913 - `message: string`

897914

898915 Human-readable error description.

899916

900 - `type: "file_not_found_error"`

901

902917 - `BetaManagedAgentsMemoryStoreArchivedRunError object`

903918

904919 A memory store referenced by the deployment is archived.

905920

921 - `type: "memory_store_archived_error"`

922

906923 - `message: string`

907924

908925 Human-readable error description.

909926

910 - `type: "memory_store_archived_error"`

911

912927 - `BetaManagedAgentsSkillNotFoundRunError object`

913928

914929 A skill referenced by the deployment's agent no longer exists.

915930

931 - `type: "skill_not_found_error"`

932

916933 - `message: string`

917934

918935 Human-readable error description.

919936

920 - `type: "skill_not_found_error"`

921

922937 - `BetaManagedAgentsSessionResourceNotFoundRunError object`

923938

924939 A referenced resource no longer exists and its kind was not reported.

925940

941 - `type: "session_resource_not_found_error"`

942

926943 - `message: string`

927944

928945 Human-readable error description.

929946

930 - `type: "session_resource_not_found_error"`

931

932947 - `BetaManagedAgentsWorkspaceArchivedRunError object`

933948

934949 The deployment's workspace was archived.

935950

951 - `type: "workspace_archived_error"`

952

936953 - `message: string`

937954

938955 Human-readable error description.

939956

940 - `type: "workspace_archived_error"`

941

942957 - `BetaManagedAgentsOrganizationDisabledRunError object`

943958

944959 The deployment's organization is disabled.

945960

961 - `type: "organization_disabled_error"`

962

946963 - `message: string`

947964

948965 Human-readable error description.

949966

950 - `type: "organization_disabled_error"`

951

952967 - `BetaManagedAgentsSessionRateLimitedRunError object`

953968

954969 Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed.

955970

971 - `type: "session_rate_limited_error"`

972

956973 - `message: string`

957974

958975 Human-readable error description.

959976

960 - `type: "session_rate_limited_error"`

961

962977 - `BetaManagedAgentsSessionCreationRejectedRunError object`

963978

964979 The session create request was rejected with a non-retryable validation error.

965980

981 - `type: "session_creation_rejected_error"`

982

966983 - `message: string`

967984

968985 Human-readable error description.

969986

970 - `type: "session_creation_rejected_error"`

971

972987 - `BetaManagedAgentsUnknownRunError object`

973988

974989 An unknown or unexpected error caused the run to fail. A fallback variant; clients that do not recognize a new error type can match on message alone.

975990

991 - `type: "unknown_error"`

992

976993 - `message: string`

977994

978995 Human-readable error description.

979996

980 - `type: "unknown_error"`

981

982997 - `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object`

983998

984999 The deployment configures resources, but its environment is self-hosted and cannot mount them.

9851000

1001 - `type: "self_hosted_resources_unsupported_error"`

1002

9861003 - `message: string`

9871004

9881005 Human-readable error description.

9891006

990 - `type: "self_hosted_resources_unsupported_error"`

991

9921007 - `BetaManagedAgentsMCPEgressBlockedRunError object`

9931008

9941009 An MCP server host used by the deployment's agent is blocked by the environment's network policy.

9951010

1011 - `type: "mcp_egress_blocked_error"`

1012

9961013 - `message: string`

9971014

9981015 Human-readable error description.

9991016

1000 - `type: "mcp_egress_blocked_error"`

1001

10021017 - `session_id: string or null`

10031018

10041019 Populated on success. Null on creation failure. Exactly one of `session_id` or `error` is non-null.

from line 1026

10111026

10121027 The run was fired by the deployment's cron schedule.

10131028

1029 - `type: "schedule"`

1030

10141031 - `scheduled_at: string`

10151032

10161033 A timestamp in RFC 3339 format

from line 1034

10171034

10181035 format: date-time

10191036

1020 - `type: "schedule"`

1021

10221037 - `BetaManagedAgentsManualTriggerContext object`

10231038

10241039 The run was started manually by creating a session directly against the deployment.

from line 1040

10251040

10261041 - `type: "manual"`

10271042

1028 - `type: "deployment_run"`

1029

10301043### Beta Managed Agents Environment Archived Run Error

10311044

10321045- `BetaManagedAgentsEnvironmentArchivedRunError object`

from line 1046

10331046

10341047 The deployment's environment was archived.

10351048

1049 - `type: "environment_archived_error"`

1050

10361051 - `message: string`

10371052

10381053 Human-readable error description.

10391054

1040 - `type: "environment_archived_error"`

1041

10421055### Beta Managed Agents Environment Not Found Run Error

10431056

10441057- `BetaManagedAgentsEnvironmentNotFoundRunError object`

from line 1058

10451058

10461059 The deployment's environment no longer exists.

10471060

1061 - `type: "environment_not_found_error"`

1062

10481063 - `message: string`

10491064

10501065 Human-readable error description.

10511066

1052 - `type: "environment_not_found_error"`

1053

10541067### Beta Managed Agents File Not Found Run Error

10551068

10561069- `BetaManagedAgentsFileNotFoundRunError object`

from line 1070

10571070

10581071 A file resource referenced by the deployment no longer exists.

10591072

1073 - `type: "file_not_found_error"`

1074

10601075 - `message: string`

10611076

10621077 Human-readable error description.

10631078

1064 - `type: "file_not_found_error"`

1065

10661079### Beta Managed Agents Manual Trigger Context

10671080

10681081- `BetaManagedAgentsManualTriggerContext object`

from line 1090

10771090

10781091 An MCP server host used by the deployment's agent is blocked by the environment's network policy.

10791092

1093 - `type: "mcp_egress_blocked_error"`

1094

10801095 - `message: string`

10811096

10821097 Human-readable error description.

10831098

1084 - `type: "mcp_egress_blocked_error"`

1085

10861099### Beta Managed Agents Memory Store Archived Run Error

10871100

10881101- `BetaManagedAgentsMemoryStoreArchivedRunError object`

from line 1102

10891102

10901103 A memory store referenced by the deployment is archived.

10911104

1105 - `type: "memory_store_archived_error"`

1106

10921107 - `message: string`

10931108

10941109 Human-readable error description.

10951110

1096 - `type: "memory_store_archived_error"`

1097

10981111### Beta Managed Agents Organization Disabled Run Error

10991112

11001113- `BetaManagedAgentsOrganizationDisabledRunError object`

from line 1114

11011114

11021115 The deployment's organization is disabled.

11031116

1117 - `type: "organization_disabled_error"`

1118

11041119 - `message: string`

11051120

11061121 Human-readable error description.

11071122

1108 - `type: "organization_disabled_error"`

1109

11101123### Beta Managed Agents Schedule Trigger Context

11111124

11121125- `BetaManagedAgentsScheduleTriggerContext object`

from line 1126

11131126

11141127 The run was fired by the deployment's cron schedule.

11151128

1129 - `type: "schedule"`

1130

11161131 - `scheduled_at: string`

11171132

11181133 A timestamp in RFC 3339 format

from line 1134

11191134

11201135 format: date-time

11211136

1122 - `type: "schedule"`

1123

11241137### Beta Managed Agents Self Hosted Resources Unsupported Run Error

11251138

11261139- `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object`

from line 1140

11271140

11281141 The deployment configures resources, but its environment is self-hosted and cannot mount them.

11291142

1143 - `type: "self_hosted_resources_unsupported_error"`

1144

11301145 - `message: string`

11311146

11321147 Human-readable error description.

11331148

1134 - `type: "self_hosted_resources_unsupported_error"`

1135

11361149### Beta Managed Agents Session Creation Rejected Run Error

11371150

11381151- `BetaManagedAgentsSessionCreationRejectedRunError object`

from line 1152

11391152

11401153 The session create request was rejected with a non-retryable validation error.

11411154

1155 - `type: "session_creation_rejected_error"`

1156

11421157 - `message: string`

11431158

11441159 Human-readable error description.

11451160

1146 - `type: "session_creation_rejected_error"`

1147

11481161### Beta Managed Agents Session Rate Limited Run Error

11491162

11501163- `BetaManagedAgentsSessionRateLimitedRunError object`

from line 1164

11511164

11521165 Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed.

11531166

1167 - `type: "session_rate_limited_error"`

1168

11541169 - `message: string`

11551170

11561171 Human-readable error description.

11571172

1158 - `type: "session_rate_limited_error"`

1159

11601173### Beta Managed Agents Session Resource Not Found Run Error

11611174

11621175- `BetaManagedAgentsSessionResourceNotFoundRunError object`

from line 1176

11631176

11641177 A referenced resource no longer exists and its kind was not reported.

11651178

1179 - `type: "session_resource_not_found_error"`

1180

11661181 - `message: string`

11671182

11681183 Human-readable error description.

11691184

1170 - `type: "session_resource_not_found_error"`

1171

11721185### Beta Managed Agents Skill Not Found Run Error

11731186

11741187- `BetaManagedAgentsSkillNotFoundRunError object`

from line 1188

11751188

11761189 A skill referenced by the deployment's agent no longer exists.

11771190

1191 - `type: "skill_not_found_error"`

1192

11781193 - `message: string`

11791194

11801195 Human-readable error description.

11811196

1182 - `type: "skill_not_found_error"`

1183

11841197### Beta Managed Agents Trigger Context

11851198

11861199- `BetaManagedAgentsTriggerContext = BetaManagedAgentsScheduleTriggerContext or BetaManagedAgentsManualTriggerContext`

from line 1204

11911204

11921205 The run was fired by the deployment's cron schedule.

11931206

1207 - `type: "schedule"`

1208

11941209 - `scheduled_at: string`

11951210

11961211 A timestamp in RFC 3339 format

from line 1212

11971212

11981213 format: date-time

11991214

1200 - `type: "schedule"`

1201

12021215 - `BetaManagedAgentsManualTriggerContext object`

12031216

12041217 The run was started manually by creating a session directly against the deployment.

from line 1234

12211234

12221235 An unknown or unexpected error caused the run to fail. A fallback variant; clients that do not recognize a new error type can match on message alone.

12231236

1237 - `type: "unknown_error"`

1238

12241239 - `message: string`

12251240

12261241 Human-readable error description.

12271242

1228 - `type: "unknown_error"`

1229

12301243### Beta Managed Agents Vault Archived Run Error

12311244

12321245- `BetaManagedAgentsVaultArchivedRunError object`

from line 1246

12331246

12341247 A vault referenced by the deployment is archived.

12351248

1249 - `type: "vault_archived_error"`

1250

12361251 - `message: string`

12371252

12381253 Human-readable error description.

12391254

1240 - `type: "vault_archived_error"`

1241

12421255### Beta Managed Agents Vault Not Found Run Error

12431256

12441257- `BetaManagedAgentsVaultNotFoundRunError object`

from line 1258

12451258

12461259 A vault referenced by the deployment no longer exists.

12471260

1261 - `type: "vault_not_found_error"`

1262

12481263 - `message: string`

12491264

12501265 Human-readable error description.

12511266

1252 - `type: "vault_not_found_error"`

1253

12541267### Beta Managed Agents Workspace Archived Run Error

12551268

12561269- `BetaManagedAgentsWorkspaceArchivedRunError object`

from line 1270

12571270

12581271 The deployment's workspace was archived.

12591272

1273 - `type: "workspace_archived_error"`

1274

12601275 - `message: string`

12611276

12621277 Human-readable error description.

1263

1264 - `type: "workspace_archived_error"`

12651278

api/beta/deployment_runs/list Changed · +80 / -71 lines

from line 1

1---

2title: List Deployment Runs

3url: https://platform.claude.com/docs/en/api/beta/deployment_runs/list

4---

5

16# List Deployment Runs

27

38**GET** `/v1/deployment_runs`

from line 69

6469

6570 - `string`

6671

67 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`

72 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`

6873

6974 - `"message-batches-2024-09-24"`

7075

from line 117

112117

113118 - `"user-profiles-2026-08-18"`

114119

120 - `"user-profiles-2026-09-04"`

121

115122 - `"advisor-tool-2026-03-01"`

116123

117124 - `"managed-agents-2026-04-01"`

from line 161

154161

155162 - `"mid-conversation-system-clear-at-2026-08-21"`

156163

164- `"anthropic-workspace-id": optional string`

165

157166## Returns

158167

159168- `data: array of BetaManagedAgentsDeploymentRun`

from line 169

160169

161170 List of deployment runs.

162171

172 - `type: "deployment_run"`

173

163174 - `id: string`

164175

165176 Unique identifier for this run (`drun_...`).

from line 179

168179

169180 A resolved agent reference with a concrete version.

170181

171 - `id: string`

172

173182 - `type: "agent"`

174183

184 - `id: string`

185

175186 - `version: number`

176187

177188 format: int32

from line 205

194205

195206 The deployment's environment was archived.

196207

208 - `type: "environment_archived_error"`

209

197210 - `message: string`

198211

199212 Human-readable error description.

200213

201 - `type: "environment_archived_error"`

202

203214 - `BetaManagedAgentsAgentArchivedRunError object`

204215

205216 The deployment's agent was archived.

206217

218 - `type: "agent_archived_error"`

219

207220 - `message: string`

208221

209222 Human-readable error description.

210223

211 - `type: "agent_archived_error"`

212

213224 - `BetaManagedAgentsEnvironmentNotFoundRunError object`

214225

215226 The deployment's environment no longer exists.

216227

228 - `type: "environment_not_found_error"`

229

217230 - `message: string`

218231

219232 Human-readable error description.

220233

221 - `type: "environment_not_found_error"`

222

223234 - `BetaManagedAgentsVaultNotFoundRunError object`

224235

225236 A vault referenced by the deployment no longer exists.

226237

238 - `type: "vault_not_found_error"`

239

227240 - `message: string`

228241

229242 Human-readable error description.

230243

231 - `type: "vault_not_found_error"`

232

233244 - `BetaManagedAgentsVaultArchivedRunError object`

234245

235246 A vault referenced by the deployment is archived.

236247

248 - `type: "vault_archived_error"`

249

237250 - `message: string`

238251

239252 Human-readable error description.

240253

241 - `type: "vault_archived_error"`

242

243254 - `BetaManagedAgentsFileNotFoundRunError object`

244255

245256 A file resource referenced by the deployment no longer exists.

246257

258 - `type: "file_not_found_error"`

259

247260 - `message: string`

248261

249262 Human-readable error description.

250263

251 - `type: "file_not_found_error"`

252

253264 - `BetaManagedAgentsMemoryStoreArchivedRunError object`

254265

255266 A memory store referenced by the deployment is archived.

256267

268 - `type: "memory_store_archived_error"`

269

257270 - `message: string`

258271

259272 Human-readable error description.

260273

261 - `type: "memory_store_archived_error"`

262

263274 - `BetaManagedAgentsSkillNotFoundRunError object`

264275

265276 A skill referenced by the deployment's agent no longer exists.

266277

278 - `type: "skill_not_found_error"`

279

267280 - `message: string`

268281

269282 Human-readable error description.

270283

271 - `type: "skill_not_found_error"`

272

273284 - `BetaManagedAgentsSessionResourceNotFoundRunError object`

274285

275286 A referenced resource no longer exists and its kind was not reported.

276287

288 - `type: "session_resource_not_found_error"`

289

277290 - `message: string`

278291

279292 Human-readable error description.

280293

281 - `type: "session_resource_not_found_error"`

282

283294 - `BetaManagedAgentsWorkspaceArchivedRunError object`

284295

285296 The deployment's workspace was archived.

286297

298 - `type: "workspace_archived_error"`

299

287300 - `message: string`

288301

289302 Human-readable error description.

290303

291 - `type: "workspace_archived_error"`

292

293304 - `BetaManagedAgentsOrganizationDisabledRunError object`

294305

295306 The deployment's organization is disabled.

296307

308 - `type: "organization_disabled_error"`

309

297310 - `message: string`

298311

299312 Human-readable error description.

300313

301 - `type: "organization_disabled_error"`

302

303314 - `BetaManagedAgentsSessionRateLimitedRunError object`

304315

305316 Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed.

306317

318 - `type: "session_rate_limited_error"`

319

307320 - `message: string`

308321

309322 Human-readable error description.

310323

311 - `type: "session_rate_limited_error"`

312

313324 - `BetaManagedAgentsSessionCreationRejectedRunError object`

314325

315326 The session create request was rejected with a non-retryable validation error.

316327

328 - `type: "session_creation_rejected_error"`

329

317330 - `message: string`

318331

319332 Human-readable error description.

320333

321 - `type: "session_creation_rejected_error"`

322

323334 - `BetaManagedAgentsUnknownRunError object`

324335

325336 An unknown or unexpected error caused the run to fail. A fallback variant; clients that do not recognize a new error type can match on message alone.

326337

338 - `type: "unknown_error"`

339

327340 - `message: string`

328341

329342 Human-readable error description.

330343

331 - `type: "unknown_error"`

332

333344 - `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object`

334345

335346 The deployment configures resources, but its environment is self-hosted and cannot mount them.

336347

348 - `type: "self_hosted_resources_unsupported_error"`

349

337350 - `message: string`

338351

339352 Human-readable error description.

340353

341 - `type: "self_hosted_resources_unsupported_error"`

342

343354 - `BetaManagedAgentsMCPEgressBlockedRunError object`

344355

345356 An MCP server host used by the deployment's agent is blocked by the environment's network policy.

346357

358 - `type: "mcp_egress_blocked_error"`

359

347360 - `message: string`

348361

349362 Human-readable error description.

350363

351 - `type: "mcp_egress_blocked_error"`

352

353364 - `session_id: string or null`

354365

355366 Populated on success. Null on creation failure. Exactly one of `session_id` or `error` is non-null.

from line 373

362373

363374 The run was fired by the deployment's cron schedule.

364375

376 - `type: "schedule"`

377

365378 - `scheduled_at: string`

366379

367380 A timestamp in RFC 3339 format

from line 381

368381

369382 format: date-time

370383

371 - `type: "schedule"`

372

373384 - `BetaManagedAgentsManualTriggerContext object`

374385

375386 The run was started manually by creating a session directly against the deployment.

376387

377388 - `type: "manual"`

378

379 - `type: "deployment_run"`

380389

381390- `next_page: optional string or null`

382391

api/beta/deployment_runs/retrieve Changed · +80 / -71 lines

from line 1

1---

2title: Get Deployment Run

3url: https://platform.claude.com/docs/en/api/beta/deployment_runs/retrieve

4---

5

16# Get Deployment Run

27

38**GET** `/v1/deployment_runs/{deployment_run_id}`

from line 21

1621

1722 - `string`

1823

19 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`

24 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`

2025

2126 - `"message-batches-2024-09-24"`

2227

from line 69

6469

6570 - `"user-profiles-2026-08-18"`

6671

72 - `"user-profiles-2026-09-04"`

73

6774 - `"advisor-tool-2026-03-01"`

6875

6976 - `"managed-agents-2026-04-01"`

from line 113

106113

107114 - `"mid-conversation-system-clear-at-2026-08-21"`

108115

116- `"anthropic-workspace-id": optional string`

117

109118## Returns

110119

111120- `BetaManagedAgentsDeploymentRun object`

from line 121

112121

113122 A persistent, append-only record of a single deployment execution. Records session creation success or failure — no session lifecycle tracking.

114123

124 - `type: "deployment_run"`

125

115126 - `id: string`

116127

117128 Unique identifier for this run (`drun_...`).

from line 131

120131

121132 A resolved agent reference with a concrete version.

122133

123 - `id: string`

124

125134 - `type: "agent"`

126135

136 - `id: string`

137

127138 - `version: number`

128139

129140 format: int32

from line 157

146157

147158 The deployment's environment was archived.

148159

160 - `type: "environment_archived_error"`

161

149162 - `message: string`

150163

151164 Human-readable error description.

152165

153 - `type: "environment_archived_error"`

154

155166 - `BetaManagedAgentsAgentArchivedRunError object`

156167

157168 The deployment's agent was archived.

158169

170 - `type: "agent_archived_error"`

171

159172 - `message: string`

160173

161174 Human-readable error description.

162175

163 - `type: "agent_archived_error"`

164

165176 - `BetaManagedAgentsEnvironmentNotFoundRunError object`

166177

167178 The deployment's environment no longer exists.

168179

180 - `type: "environment_not_found_error"`

181

169182 - `message: string`

170183

171184 Human-readable error description.

172185

173 - `type: "environment_not_found_error"`

174

175186 - `BetaManagedAgentsVaultNotFoundRunError object`

176187

177188 A vault referenced by the deployment no longer exists.

178189

190 - `type: "vault_not_found_error"`

191

179192 - `message: string`

180193

181194 Human-readable error description.

182195

183 - `type: "vault_not_found_error"`

184

185196 - `BetaManagedAgentsVaultArchivedRunError object`

186197

187198 A vault referenced by the deployment is archived.

188199

200 - `type: "vault_archived_error"`

201

189202 - `message: string`

190203

191204 Human-readable error description.

192205

193 - `type: "vault_archived_error"`

194

195206 - `BetaManagedAgentsFileNotFoundRunError object`

196207

197208 A file resource referenced by the deployment no longer exists.

198209

210 - `type: "file_not_found_error"`

211

199212 - `message: string`

200213

201214 Human-readable error description.

202215

203 - `type: "file_not_found_error"`

204

205216 - `BetaManagedAgentsMemoryStoreArchivedRunError object`

206217

207218 A memory store referenced by the deployment is archived.

208219

220 - `type: "memory_store_archived_error"`

221

209222 - `message: string`

210223

211224 Human-readable error description.

212225

213 - `type: "memory_store_archived_error"`

214

215226 - `BetaManagedAgentsSkillNotFoundRunError object`

216227

217228 A skill referenced by the deployment's agent no longer exists.

218229

230 - `type: "skill_not_found_error"`

231

219232 - `message: string`

220233

221234 Human-readable error description.

222235

223 - `type: "skill_not_found_error"`

224

225236 - `BetaManagedAgentsSessionResourceNotFoundRunError object`

226237

227238 A referenced resource no longer exists and its kind was not reported.

228239

240 - `type: "session_resource_not_found_error"`

241

229242 - `message: string`

230243

231244 Human-readable error description.

232245

233 - `type: "session_resource_not_found_error"`

234

235246 - `BetaManagedAgentsWorkspaceArchivedRunError object`

236247

237248 The deployment's workspace was archived.

238249

250 - `type: "workspace_archived_error"`

251

239252 - `message: string`

240253

241254 Human-readable error description.

242255

243 - `type: "workspace_archived_error"`

244

245256 - `BetaManagedAgentsOrganizationDisabledRunError object`

246257

247258 The deployment's organization is disabled.

248259

260 - `type: "organization_disabled_error"`

261

249262 - `message: string`

250263

251264 Human-readable error description.

252265

253 - `type: "organization_disabled_error"`

254

255266 - `BetaManagedAgentsSessionRateLimitedRunError object`

256267

257268 Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed.

258269

270 - `type: "session_rate_limited_error"`

271

259272 - `message: string`

260273

261274 Human-readable error description.

262275

263 - `type: "session_rate_limited_error"`

264

265276 - `BetaManagedAgentsSessionCreationRejectedRunError object`

266277

267278 The session create request was rejected with a non-retryable validation error.

268279

280 - `type: "session_creation_rejected_error"`

281

269282 - `message: string`

270283

271284 Human-readable error description.

272285

273 - `type: "session_creation_rejected_error"`

274

275286 - `BetaManagedAgentsUnknownRunError object`

276287

277288 An unknown or unexpected error caused the run to fail. A fallback variant; clients that do not recognize a new error type can match on message alone.

278289

290 - `type: "unknown_error"`

291

279292 - `message: string`

280293

281294 Human-readable error description.

282295

283 - `type: "unknown_error"`

284

285296 - `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object`

286297

287298 The deployment configures resources, but its environment is self-hosted and cannot mount them.

288299

300 - `type: "self_hosted_resources_unsupported_error"`

301

289302 - `message: string`

290303

291304 Human-readable error description.

292305

293 - `type: "self_hosted_resources_unsupported_error"`

294

295306 - `BetaManagedAgentsMCPEgressBlockedRunError object`

296307

297308 An MCP server host used by the deployment's agent is blocked by the environment's network policy.

298309

310 - `type: "mcp_egress_blocked_error"`

311

299312 - `message: string`

300313

301314 Human-readable error description.

302315

303 - `type: "mcp_egress_blocked_error"`

304

305316 - `session_id: string or null`

306317

307318 Populated on success. Null on creation failure. Exactly one of `session_id` or `error` is non-null.

from line 325

314325

315326 The run was fired by the deployment's cron schedule.

316327

328 - `type: "schedule"`

329

317330 - `scheduled_at: string`

318331

319332 A timestamp in RFC 3339 format

from line 333

320333

321334 format: date-time

322335

323 - `type: "schedule"`

324

325336 - `BetaManagedAgentsManualTriggerContext object`

326337

327338 The run was started manually by creating a session directly against the deployment.

328339

329340 - `type: "manual"`

330

331 - `type: "deployment_run"`

332341

333342## Example

334343

api/beta/deployments Changed · +4428 / -4391 lines

Nothing in the body moved in this read. What changed is above.

api/beta/deployments/archive Changed · +198 / -189 lines

from line 1

1---

2title: Archive Deployment

3url: https://platform.claude.com/docs/en/api/beta/deployments/archive

4---

5

16# Archive Deployment

27

38**POST** `/v1/deployments/{deployment_id}/archive`

from line 21

1621

1722 - `string`

1823

19 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`

24 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`

2025

2126 - `"message-batches-2024-09-24"`

2227

from line 69

6469

6570 - `"user-profiles-2026-08-18"`

6671

72 - `"user-profiles-2026-09-04"`

73

6774 - `"advisor-tool-2026-03-01"`

6875

6976 - `"managed-agents-2026-04-01"`

from line 113

106113

107114 - `"mid-conversation-system-clear-at-2026-08-21"`

108115

116- `"anthropic-workspace-id": optional string`

117

109118## Returns

110119

111120- `BetaManagedAgentsDeployment object`

from line 121

112121

113122 A deployment is a configured instance of an agent — it binds the agent to everything needed to run it autonomously: an environment, credentials, initial events, and an optional schedule.

114123

124 - `type: "deployment"`

125

115126 - `id: string`

116127

117128 Unique identifier for this deployment.

from line 131

120131

121132 A resolved agent reference with a concrete version.

122133

123 - `id: string`

124

125134 - `type: "agent"`

126135

136 - `id: string`

137

127138 - `version: number`

128139

129140 format: int32

from line 167

156167

157168 A user message sent to the session.

158169

170 - `type: "user.message"`

171

159172 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`

160173

161174 Array of content blocks for the user message.

from line 177

164177

165178 Regular text content.

166179

180 - `type: "text"`

181

167182 - `text: string`

168183

169184 The text content.

from line 185

170185

171186 minLength: 1

172187

173 - `type: "text"`

174

175188 - `BetaManagedAgentsImageBlock object`

176189

177190 Image content specified directly as base64 data or as a reference via a URL.

178191

192 - `type: "image"`

193

179194 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`

180195

181196 Union type for image source variants.

from line 199

184199

185200 Base64-encoded image data.

186201

202 - `type: "base64"`

203

187204 - `data: string`

188205

189206 Base64-encoded image data.

from line 213

196213

197214 minLength: 1

198215

199 - `type: "base64"`

200

201216 - `BetaManagedAgentsURLImageSource object`

202217

203218 Image referenced by URL.

from line 229

214229

215230 Image referenced by file ID.

216231

232 - `type: "file"`

233

217234 - `file_id: string`

218235

219236 ID of a previously uploaded file.

from line 237

220237

221238 minLength: 1

222239

223 - `type: "file"`

224

225 - `type: "image"`

226

227240 - `BetaManagedAgentsDocumentBlock object`

228241

229242 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

230243

244 - `type: "document"`

245

231246 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`

232247

233248 Union type for document source variants.

from line 251

236251

237252 Base64-encoded document data.

238253

254 - `type: "base64"`

255

239256 - `data: string`

240257

241258 Base64-encoded document data.

from line 265

248265

249266 minLength: 1

250267

251 - `type: "base64"`

252

253268 - `BetaManagedAgentsPlainTextDocumentSource object`

254269

255270 Plain text document content.

256271

272 - `type: "text"`

273

257274 - `data: string`

258275

259276 The plain text content.

from line 281

264281

265282 MIME type of the text content. Must be "text/plain".

266283

267 - `type: "text"`

268

269284 - `BetaManagedAgentsURLDocumentSource object`

270285

271286 Document referenced by URL.

from line 297

282297

283298 Document referenced by file ID.

284299

300 - `type: "file"`

301

285302 - `file_id: string`

286303

287304 ID of a previously uploaded file.

from line 305

288305

289306 minLength: 1

290307

291 - `type: "file"`

292

293 - `type: "document"`

294

295308 - `context: optional string or null`

296309

297310 Additional context about the document for the model.

from line 319

306319

307320 - `type: "redacted"`

308321

309 - `type: "user.message"`

310

311322 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`

312323

313324 An outcome the agent should work toward. The agent begins work on receipt.

314325

326 - `type: "user.define_outcome"`

327

315328 - `description: string`

316329

317330 What the agent should produce. This is the task specification.

from line 337

324337

325338 Rubric referenced by a file uploaded via the Files API.

326339

340 - `type: "file"`

341

327342 - `file_id: string`

328343

329344 ID of the rubric file.

330345

331 - `type: "file"`

332

333346 - `BetaManagedAgentsTextRubric object`

334347

335348 Rubric content provided inline as text.

336349

350 - `type: "text"`

351

337352 - `content: string`

338353

339354 Rubric content. Plain text or markdown — the grader treats it as freeform text.

340355

341 - `type: "text"`

342

343 - `type: "user.define_outcome"`

344

345356 - `max_iterations: optional number or null`

346357

347358 Eval→revision cycles before giving up. Default 3, max 20.

from line 363

352363

353364 Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt.

354365

366 - `type: "system.message"`

367

355368 - `content: array of BetaManagedAgentsSystemContentBlock`

356369

357370 System content blocks to append. Text-only.

358371

372 - `type: "text"`

373

359374 - `text: string`

360375

361376 The text content.

from line 377

362377

363378 minLength: 1

364379

365 - `type: "text"`

366

367 - `type: "system.message"`

368

369380 - `metadata: map[string]`

370381

371382 Arbitrary key-value metadata. Maximum 16 pairs.

from line 399

388399

389400 A scheduled fire recorded a failed run whose error auto-pauses the deployment.

390401

402 - `type: "error"`

403

391404 - `error: BetaManagedAgentsDeploymentPausedReasonError`

392405

393406 The error that triggered an auto-pause. Matches the failed run's `error.type`.

from line 489

476489

477490 - `type: "mcp_egress_blocked_error"`

478491

479 - `type: "error"`

480

481492 - `resources: array of BetaManagedAgentsSessionResourceConfig`

482493

483494 Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.

from line 509

498509

499510 - `BetaManagedAgentsBranchCheckout object`

500511

512 - `type: "branch"`

513

501514 - `name: string`

502515

503516 Branch name to check out.

from line 517

504517

505518 minLength: 1, maxLength: 255

506519

507 - `type: "branch"`

508

509520 - `BetaManagedAgentsCommitCheckout object`

510521

522 - `type: "commit"`

523

511524 - `sha: string`

512525

513526 Full commit SHA to check out.

from line 527

514527

515528 minLength: 7, maxLength: 64

516529

517 - `type: "commit"`

518

519530 - `mount_path: optional string or null`

520531

521532 Mount path in the container. Defaults to `/workspace/<repo-name>`.

from line 535

524535

525536 A file mounted into each session's container.

526537

538 - `type: "file"`

539

527540 - `file_id: string`

528541

529542 ID of a previously uploaded file.

530543

531 - `type: "file"`

532

533544 - `mount_path: optional string or null`

534545

535546 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

from line 549

538549

539550 A memory store attached to each session created from this deployment.

540551

552 - `type: "memory_store"`

553

541554 - `memory_store_id: string`

542555

543556 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

544557

545 - `type: "memory_store"`

546

547558 - `access: optional "read_write" or "read_only" or null`

548559

549560 Access mode for an attached memory store.

from line 571

560571

561572 5-field POSIX cron schedule with computed runtime timestamps.

562573

574 - `type: "cron"`

575

563576 - `expression: string`

564577

565578 5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).

from line 585

572585

573586 minLength: 1

574587

575 - `type: "cron"`

576

577588 - `last_run_at: optional string or null`

578589

579590 A timestamp in RFC 3339 format

from line 603

592603

593604 - `"paused"`

594605

595 - `type: "deployment"`

596

597606 - `updated_at: string`

598607

599608 A timestamp in RFC 3339 format

from line 617

608617

609618 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.

610619

620 - `type: "limit"`

621

611622 - `max_list_cost: BetaMonetaryAmount`

612623

613624 A monetary amount in a specific currency.

from line 630

619630 - `currency: BetaCurrency`

620631

621632 Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.

622

623 - `type: "limit"`

624633

625634## Example

626635

api/beta/deployments/create Changed · +873 / -864 lines

from line 1

1---

2title: Create Deployment

3url: https://platform.claude.com/docs/en/api/beta/deployments/create

4---

5

16# Create Deployment

27

38**POST** `/v1/deployments`

from line 17

1217

1318 - `string`

1419

15 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`

20 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`

1621

1722 - `"message-batches-2024-09-24"`

1823

from line 65

6065

6166 - `"user-profiles-2026-08-18"`

6267

68 - `"user-profiles-2026-09-04"`

69

6370 - `"advisor-tool-2026-03-01"`

6471

6572 - `"managed-agents-2026-04-01"`

from line 109

102109

103110 - `"mid-conversation-system-clear-at-2026-08-21"`

104111

112- `"anthropic-workspace-id": optional string`

113

105114## Body parameters

106115

107116- `agent: string or BetaManagedAgentsAgentParams`

from line 123

114123

115124 Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version

116125

126 - `type: "agent"`

127

117128 - `id: string`

118129

119130 The `agent` ID.

from line 131

120131

121132 minLength: 1, maxLength: 128

122133

123 - `type: "agent"`

124

125134 - `version: optional number`

126135

127136 The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.

from line 151

142151

143152 Parameters for sending a user message to the session.

144153

154 - `type: "user.message"`

155

145156 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`

146157

147158 Array of content blocks for the user message.

from line 161

150161

151162 Regular text content.

152163

164 - `type: "text"`

165

153166 - `text: string`

154167

155168 The text content.

from line 169

156169

157170 minLength: 1

158171

159 - `type: "text"`

160

161172 - `BetaManagedAgentsImageBlock object`

162173

163174 Image content specified directly as base64 data or as a reference via a URL.

164175

176 - `type: "image"`

177

165178 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`

166179

167180 Union type for image source variants.

from line 183

170183

171184 Base64-encoded image data.

172185

186 - `type: "base64"`

187

173188 - `data: string`

174189

175190 Base64-encoded image data.

from line 197

182197

183198 minLength: 1

184199

185 - `type: "base64"`

186

187200 - `BetaManagedAgentsURLImageSource object`

188201

189202 Image referenced by URL.

from line 213

200213

201214 Image referenced by file ID.

202215

216 - `type: "file"`

217

203218 - `file_id: string`

204219

205220 ID of a previously uploaded file.

from line 221

206221

207222 minLength: 1

208223

209 - `type: "file"`

210

211 - `type: "image"`

212

213224 - `BetaManagedAgentsDocumentBlock object`

214225

215226 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

216227

228 - `type: "document"`

229

217230 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`

218231

219232 Union type for document source variants.

from line 235

222235

223236 Base64-encoded document data.

224237

238 - `type: "base64"`

239

225240 - `data: string`

226241

227242 Base64-encoded document data.

from line 249

234249

235250 minLength: 1

236251

237 - `type: "base64"`

238

239252 - `BetaManagedAgentsPlainTextDocumentSource object`

240253

241254 Plain text document content.

242255

256 - `type: "text"`

257

243258 - `data: string`

244259

245260 The plain text content.

from line 265

250265

251266 MIME type of the text content. Must be "text/plain".

252267

253 - `type: "text"`

254

255268 - `BetaManagedAgentsURLDocumentSource object`

256269

257270 Document referenced by URL.

from line 281

268281

269282 Document referenced by file ID.

270283

284 - `type: "file"`

285

271286 - `file_id: string`

272287

273288 ID of a previously uploaded file.

from line 289

274289

275290 minLength: 1

276291

277 - `type: "file"`

278

279 - `type: "document"`

280

281292 - `context: optional string or null`

282293

283294 Additional context about the document for the model.

from line 303

292303

293304 - `type: "redacted"`

294305

295 - `type: "user.message"`

296

297306 - `BetaManagedAgentsUserDefineOutcomeEventParams object`

298307

299308 Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.

300309

310 - `type: "user.define_outcome"`

311

301312 - `description: string`

302313

303314 What the agent should produce. This is the task specification.

from line 321

310321

311322 Rubric referenced by a file uploaded via the Files API.

312323

324 - `type: "file"`

325

313326 - `file_id: string`

314327

315328 ID of the rubric file.

316329

317 - `type: "file"`

318

319330 - `BetaManagedAgentsTextRubricParams object`

320331

321332 Rubric content provided inline as text.

322333

334 - `type: "text"`

335

323336 - `content: string`

324337

325338 Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.

from line 339

326339

327340 maxLength: 262144

328341

329 - `type: "text"`

330

331 - `type: "user.define_outcome"`

332

333342 - `max_iterations: optional number or null`

334343

335344 Eval→revision cycles before giving up. Default 3, max 20.

from line 349

340349

341350 Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt. At most one per request: it must be the final event and immediately follow the `user.message`, `user.tool_result`, or `user.custom_tool_result` it accompanies. Only supported on models that accept mid-conversation system messages.

342351

352 - `type: "system.message"`

353

343354 - `content: array of BetaManagedAgentsSystemContentBlock`

344355

345356 System content blocks to append. Text-only.

346357

358 - `type: "text"`

359

347360 - `text: string`

348361

349362 The text content.

from line 363

350363

351364 minLength: 1

352365

353 - `type: "text"`

354

355 - `type: "system.message"`

356

357366- `name: string`

358367

359368 Human-readable name for the deployment.

from line 373

364373

365374 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.

366375

376 - `type: "limit"`

377

367378 - `max_list_cost: BetaMonetaryAmount`

368379

369380 A monetary amount in a specific currency.

from line 387

376387

377388 Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.

378389

379 - `type: "limit"`

380

381390- `description: optional string or null`

382391

383392 Description of what the deployment does.

from line 405

396405

397406 Mount a GitHub repository into the session's container.

398407

399 - `authorization_token: string`

400

401 GitHub authorization token used to clone the repository.

402

403 minLength: 1, maxLength: 4096

404

405408 - `type: "github_repository"`

406409

407410 - `url: string`

from line 413

410413

411414 minLength: 1, maxLength: 2048

412415

416 - `authorization_token: optional string`

417

418 GitHub authorization token used to clone the repository. Required for private repositories; optional for public ones.

419

420 minLength: 1, maxLength: 4096

421

413422 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`

414423

415424 Branch or commit to check out. Defaults to the repository's default branch.

from line 425

416425

417426 - `BetaManagedAgentsBranchCheckout object`

418427

428 - `type: "branch"`

429

419430 - `name: string`

420431

421432 Branch name to check out.

from line 433

422433

423434 minLength: 1, maxLength: 255

424435

425 - `type: "branch"`

426

427436 - `BetaManagedAgentsCommitCheckout object`

428437

438 - `type: "commit"`

439

429440 - `sha: string`

430441

431442 Full commit SHA to check out.

from line 443

432443

433444 minLength: 7, maxLength: 64

434445

435 - `type: "commit"`

436

437446 - `mount_path: optional string or null`

438447

439448 Mount path in the container. Defaults to `/workspace/<repo-name>`.

from line 453

444453

445454 Mount a file uploaded via the Files API into the session.

446455

456 - `type: "file"`

457

447458 - `file_id: string`

448459

449460 ID of a previously uploaded file.

from line 461

450461

451462 minLength: 1, maxLength: 128

452463

453 - `type: "file"`

454

455464 - `mount_path: optional string or null`

456465

457466 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

from line 471

462471

463472 Parameters for attaching a memory store to an agent session.

464473

474 - `type: "memory_store"`

475

465476 - `memory_store_id: string`

466477

467478 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

468479

469 - `type: "memory_store"`

470

471480 - `access: optional "read_write" or "read_only" or null`

472481

473482 Access mode for an attached memory store.

from line 495

486495

487496 5-field POSIX cron schedule. Literal wall-clock matching in the configured timezone.

488497

498 - `type: "cron"`

499

489500 - `expression: string`

490501

491502 5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).

from line 509

498509

499510 minLength: 1

500511

501 - `type: "cron"`

502

503512- `vault_ids: optional array of string`

504513

505514 Vault IDs for stored credentials the agent can use during sessions created from this deployment. Maximum 50.

from line 519

510519

511520 A deployment is a configured instance of an agent — it binds the agent to everything needed to run it autonomously: an environment, credentials, initial events, and an optional schedule.

512521

522 - `type: "deployment"`

523

513524 - `id: string`

514525

515526 Unique identifier for this deployment.

from line 529

518529

519530 A resolved agent reference with a concrete version.

520531

521 - `id: string`

522

523532 - `type: "agent"`

524533

534 - `id: string`

535

525536 - `version: number`

526537

527538 format: int32

from line 565

554565

555566 A user message sent to the session.

556567

568 - `type: "user.message"`

569

557570 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`

558571

559572 Array of content blocks for the user message.

from line 575

562575

563576 Regular text content.

564577

578 - `type: "text"`

579

565580 - `text: string`

566581

567582 The text content.

from line 583

568583

569584 minLength: 1

570585

571 - `type: "text"`

572

573586 - `BetaManagedAgentsImageBlock object`

574587

575588 Image content specified directly as base64 data or as a reference via a URL.

576589

590 - `type: "image"`

591

577592 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`

578593

579594 Union type for image source variants.

from line 597

582597

583598 Base64-encoded image data.

584599

600 - `type: "base64"`

601

585602 - `data: string`

586603

587604 Base64-encoded image data.

from line 611

594611

595612 minLength: 1

596613

597 - `type: "base64"`

598

599614 - `BetaManagedAgentsURLImageSource object`

600615

601616 Image referenced by URL.

from line 627

612627

613628 Image referenced by file ID.

614629

630 - `type: "file"`

631

615632 - `file_id: string`

616633

617634 ID of a previously uploaded file.

from line 635

618635

619636 minLength: 1

620637

621 - `type: "file"`

622

623 - `type: "image"`

624

625638 - `BetaManagedAgentsDocumentBlock object`

626639

627640 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

628641

642 - `type: "document"`

643

629644 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`

630645

631646 Union type for document source variants.

from line 649

634649

635650 Base64-encoded document data.

636651

652 - `type: "base64"`

653

637654 - `data: string`

638655

639656 Base64-encoded document data.

from line 663

646663

647664 minLength: 1

648665

649 - `type: "base64"`

650

651666 - `BetaManagedAgentsPlainTextDocumentSource object`

652667

653668 Plain text document content.

654669

670 - `type: "text"`

671

655672 - `data: string`

656673

657674 The plain text content.

from line 679

662679

663680 MIME type of the text content. Must be "text/plain".

664681

665 - `type: "text"`

666

667682 - `BetaManagedAgentsURLDocumentSource object`

668683

669684 Document referenced by URL.

from line 695

680695

681696 Document referenced by file ID.

682697

698 - `type: "file"`

699

683700 - `file_id: string`

684701

685702 ID of a previously uploaded file.

from line 703

686703

687704 minLength: 1

688705

689 - `type: "file"`

690

691 - `type: "document"`

692

693706 - `context: optional string or null`

694707

695708 Additional context about the document for the model.

from line 717

704717

705718 - `type: "redacted"`

706719

707 - `type: "user.message"`

708

709720 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`

710721

711722 An outcome the agent should work toward. The agent begins work on receipt.

712723

724 - `type: "user.define_outcome"`

725

713726 - `description: string`

714727

715728 What the agent should produce. This is the task specification.

from line 735

722735

723736 Rubric referenced by a file uploaded via the Files API.

724737

738 - `type: "file"`

739

725740 - `file_id: string`

726741

727742 ID of the rubric file.

728743

729 - `type: "file"`

730

731744 - `BetaManagedAgentsTextRubric object`

732745

733746 Rubric content provided inline as text.

734747

748 - `type: "text"`

749

735750 - `content: string`

736751

737752 Rubric content. Plain text or markdown — the grader treats it as freeform text.

738753

739 - `type: "text"`

740

741 - `type: "user.define_outcome"`

742

743754 - `max_iterations: optional number or null`

744755

745756 Eval→revision cycles before giving up. Default 3, max 20.

from line 761

750761

751762 Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt.

752763

764 - `type: "system.message"`

765

753766 - `content: array of BetaManagedAgentsSystemContentBlock`

754767

755768 System content blocks to append. Text-only.

756769

770 - `type: "text"`

771

757772 - `text: string`

758773

759774 The text content.

from line 775

760775

761776 minLength: 1

762777

763 - `type: "text"`

764

765 - `type: "system.message"`

766

767778 - `metadata: map[string]`

768779

769780 Arbitrary key-value metadata. Maximum 16 pairs.

from line 797

786797

787798 A scheduled fire recorded a failed run whose error auto-pauses the deployment.

788799

800 - `type: "error"`

801

789802 - `error: BetaManagedAgentsDeploymentPausedReasonError`

790803

791804 The error that triggered an auto-pause. Matches the failed run's `error.type`.

from line 887

874887

875888 - `type: "mcp_egress_blocked_error"`

876889

877 - `type: "error"`

878

879890 - `resources: array of BetaManagedAgentsSessionResourceConfig`

880891

881892 Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.

from line 907

896907

897908 - `BetaManagedAgentsBranchCheckout object`

898909

910 - `type: "branch"`

911

899912 - `name: string`

900913

901914 Branch name to check out.

from line 915

902915

903916 minLength: 1, maxLength: 255

904917

905 - `type: "branch"`

906

907918 - `BetaManagedAgentsCommitCheckout object`

908919

920 - `type: "commit"`

921

909922 - `sha: string`

910923

911924 Full commit SHA to check out.

from line 925

912925

913926 minLength: 7, maxLength: 64

914927

915 - `type: "commit"`

916

917928 - `mount_path: optional string or null`

918929

919930 Mount path in the container. Defaults to `/workspace/<repo-name>`.

from line 933

922933

923934 A file mounted into each session's container.

924935

936 - `type: "file"`

937

925938 - `file_id: string`

926939

927940 ID of a previously uploaded file.

928941

929 - `type: "file"`

930

931942 - `mount_path: optional string or null`

932943

933944 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

from line 947

936947

937948 A memory store attached to each session created from this deployment.

938949

950 - `type: "memory_store"`

951

939952 - `memory_store_id: string`

940953

941954 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

942955

943 - `type: "memory_store"`

944

945956 - `access: optional "read_write" or "read_only" or null`

946957

947958 Access mode for an attached memory store.

from line 969

958969

959970 5-field POSIX cron schedule with computed runtime timestamps.

960971

972 - `type: "cron"`

973

961974 - `expression: string`

962975

963976 5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).

from line 983

970983

971984 minLength: 1

972985

973 - `type: "cron"`

974

975986 - `last_run_at: optional string or null`

976987

977988 A timestamp in RFC 3339 format

from line 1001

9901001

9911002 - `"paused"`

9921003

993 - `type: "deployment"`

994

9951004 - `updated_at: string`

9961005

9971006 A timestamp in RFC 3339 format

from line 1015

10061015

10071016 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.

10081017

1018 - `type: "limit"`

1019

10091020 - `max_list_cost: BetaMonetaryAmount`

10101021

10111022 A monetary amount in a specific currency.

from line 1028

10171028 - `currency: BetaCurrency`

10181029

10191030 Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.

1020

1021 - `type: "limit"`

10221031

10231032## Example

10241033

api/beta/deployments/list Changed · +198 / -189 lines

from line 1

1---

2title: List Deployments

3url: https://platform.claude.com/docs/en/api/beta/deployments/list

4---

5

16# List Deployments

27

38**GET** `/v1/deployments`

from line 57

5257

5358 - `string`

5459

55 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`

60 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`

5661

5762 - `"message-batches-2024-09-24"`

5863

from line 105

100105

101106 - `"user-profiles-2026-08-18"`

102107

108 - `"user-profiles-2026-09-04"`

109

103110 - `"advisor-tool-2026-03-01"`

104111

105112 - `"managed-agents-2026-04-01"`

from line 149

142149

143150 - `"mid-conversation-system-clear-at-2026-08-21"`

144151

152- `"anthropic-workspace-id": optional string`

153

145154## Returns

146155

147156- `data: array of BetaManagedAgentsDeployment`

from line 157

148157

149158 List of deployments.

150159

160 - `type: "deployment"`

161

151162 - `id: string`

152163

153164 Unique identifier for this deployment.

from line 167

156167

157168 A resolved agent reference with a concrete version.

158169

159 - `id: string`

160

161170 - `type: "agent"`

162171

172 - `id: string`

173

163174 - `version: number`

164175

165176 format: int32

from line 203

192203

193204 A user message sent to the session.

194205

206 - `type: "user.message"`

207

195208 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`

196209

197210 Array of content blocks for the user message.

from line 213

200213

201214 Regular text content.

202215

216 - `type: "text"`

217

203218 - `text: string`

204219

205220 The text content.

from line 221

206221

207222 minLength: 1

208223

209 - `type: "text"`

210

211224 - `BetaManagedAgentsImageBlock object`

212225

213226 Image content specified directly as base64 data or as a reference via a URL.

214227

228 - `type: "image"`

229

215230 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`

216231

217232 Union type for image source variants.

from line 235

220235

221236 Base64-encoded image data.

222237

238 - `type: "base64"`

239

223240 - `data: string`

224241

225242 Base64-encoded image data.

from line 249

232249

233250 minLength: 1

234251

235 - `type: "base64"`

236

237252 - `BetaManagedAgentsURLImageSource object`

238253

239254 Image referenced by URL.

from line 265

250265

251266 Image referenced by file ID.

252267

268 - `type: "file"`

269

253270 - `file_id: string`

254271

255272 ID of a previously uploaded file.

from line 273

256273

257274 minLength: 1

258275

259 - `type: "file"`

260

261 - `type: "image"`

262

263276 - `BetaManagedAgentsDocumentBlock object`

264277

265278 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

266279

280 - `type: "document"`

281

267282 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`

268283

269284 Union type for document source variants.

from line 287

272287

273288 Base64-encoded document data.

274289

290 - `type: "base64"`

291

275292 - `data: string`

276293

277294 Base64-encoded document data.

from line 301

284301

285302 minLength: 1

286303

287 - `type: "base64"`

288

289304 - `BetaManagedAgentsPlainTextDocumentSource object`

290305

291306 Plain text document content.

292307

308 - `type: "text"`

309

293310 - `data: string`

294311

295312 The plain text content.

from line 317

300317

301318 MIME type of the text content. Must be "text/plain".

302319

303 - `type: "text"`

304

305320 - `BetaManagedAgentsURLDocumentSource object`

306321

307322 Document referenced by URL.

from line 333

318333

319334 Document referenced by file ID.

320335

336 - `type: "file"`

337

321338 - `file_id: string`

322339

323340 ID of a previously uploaded file.

from line 341

324341

325342 minLength: 1

326343

327 - `type: "file"`

328

329 - `type: "document"`

330

331344 - `context: optional string or null`

332345

333346 Additional context about the document for the model.

from line 355

342355

343356 - `type: "redacted"`

344357

345 - `type: "user.message"`

346

347358 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`

348359

349360 An outcome the agent should work toward. The agent begins work on receipt.

350361

362 - `type: "user.define_outcome"`

363

351364 - `description: string`

352365

353366 What the agent should produce. This is the task specification.

from line 373

360373

361374 Rubric referenced by a file uploaded via the Files API.

362375

376 - `type: "file"`

377

363378 - `file_id: string`

364379

365380 ID of the rubric file.

366381

367 - `type: "file"`

368

369382 - `BetaManagedAgentsTextRubric object`

370383

371384 Rubric content provided inline as text.

372385

386 - `type: "text"`

387

373388 - `content: string`

374389

375390 Rubric content. Plain text or markdown — the grader treats it as freeform text.

376391

377 - `type: "text"`

378

379 - `type: "user.define_outcome"`

380

381392 - `max_iterations: optional number or null`

382393

383394 Eval→revision cycles before giving up. Default 3, max 20.

from line 399

388399

389400 Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt.

390401

402 - `type: "system.message"`

403

391404 - `content: array of BetaManagedAgentsSystemContentBlock`

392405

393406 System content blocks to append. Text-only.

394407

408 - `type: "text"`

409

395410 - `text: string`

396411

397412 The text content.

from line 413

398413

399414 minLength: 1

400415

401 - `type: "text"`

402

403 - `type: "system.message"`

404

405416 - `metadata: map[string]`

406417

407418 Arbitrary key-value metadata. Maximum 16 pairs.

from line 435

424435

425436 A scheduled fire recorded a failed run whose error auto-pauses the deployment.

426437

438 - `type: "error"`

439

427440 - `error: BetaManagedAgentsDeploymentPausedReasonError`

428441

429442 The error that triggered an auto-pause. Matches the failed run's `error.type`.

from line 525

512525

513526 - `type: "mcp_egress_blocked_error"`

514527

515 - `type: "error"`

516

517528 - `resources: array of BetaManagedAgentsSessionResourceConfig`

518529

519530 Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.

from line 545

534545

535546 - `BetaManagedAgentsBranchCheckout object`

536547

548 - `type: "branch"`

549

537550 - `name: string`

538551

539552 Branch name to check out.

from line 553

540553

541554 minLength: 1, maxLength: 255

542555

543 - `type: "branch"`

544

545556 - `BetaManagedAgentsCommitCheckout object`

546557

558 - `type: "commit"`

559

547560 - `sha: string`

548561

549562 Full commit SHA to check out.

from line 563

550563

551564 minLength: 7, maxLength: 64

552565

553 - `type: "commit"`

554

555566 - `mount_path: optional string or null`

556567

557568 Mount path in the container. Defaults to `/workspace/<repo-name>`.

from line 571

560571

561572 A file mounted into each session's container.

562573

574 - `type: "file"`

575

563576 - `file_id: string`

564577

565578 ID of a previously uploaded file.

566579

567 - `type: "file"`

568

569580 - `mount_path: optional string or null`

570581

571582 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

from line 585

574585

575586 A memory store attached to each session created from this deployment.

576587

588 - `type: "memory_store"`

589

577590 - `memory_store_id: string`

578591

579592 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

580593

581 - `type: "memory_store"`

582

583594 - `access: optional "read_write" or "read_only" or null`

584595

585596 Access mode for an attached memory store.

from line 607

596607

597608 5-field POSIX cron schedule with computed runtime timestamps.

598609

610 - `type: "cron"`

611

599612 - `expression: string`

600613

601614 5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).

from line 621

608621

609622 minLength: 1

610623

611 - `type: "cron"`

612

613624 - `last_run_at: optional string or null`

614625

615626 A timestamp in RFC 3339 format

from line 639

628639

629640 - `"paused"`

630641

631 - `type: "deployment"`

632

633642 - `updated_at: string`

634643

635644 A timestamp in RFC 3339 format

from line 653

644653

645654 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.

646655

656 - `type: "limit"`

657

647658 - `max_list_cost: BetaMonetaryAmount`

648659

649660 A monetary amount in a specific currency.

from line 666

655666 - `currency: BetaCurrency`

656667

657668 Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.

658

659 - `type: "limit"`

660669

661670- `next_page: optional string or null`

662671

api/beta/deployments/pause Changed · +198 / -189 lines

from line 1

1---

2title: Pause Deployment

3url: https://platform.claude.com/docs/en/api/beta/deployments/pause

4---

5

16# Pause Deployment

27

38**POST** `/v1/deployments/{deployment_id}/pause`

from line 21

1621

1722 - `string`

1823

19 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`

24 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`

2025

2126 - `"message-batches-2024-09-24"`

2227

from line 69

6469

6570 - `"user-profiles-2026-08-18"`

6671

72 - `"user-profiles-2026-09-04"`

73

6774 - `"advisor-tool-2026-03-01"`

6875

6976 - `"managed-agents-2026-04-01"`

from line 113

106113

107114 - `"mid-conversation-system-clear-at-2026-08-21"`

108115

116- `"anthropic-workspace-id": optional string`

117

109118## Returns

110119

111120- `BetaManagedAgentsDeployment object`

from line 121

112121

113122 A deployment is a configured instance of an agent — it binds the agent to everything needed to run it autonomously: an environment, credentials, initial events, and an optional schedule.

114123

124 - `type: "deployment"`

125

115126 - `id: string`

116127

117128 Unique identifier for this deployment.

from line 131

120131

121132 A resolved agent reference with a concrete version.

122133

123 - `id: string`

124

125134 - `type: "agent"`

126135

136 - `id: string`

137

127138 - `version: number`

128139

129140 format: int32

from line 167

156167

157168 A user message sent to the session.

158169

170 - `type: "user.message"`

171

159172 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`

160173

161174 Array of content blocks for the user message.

from line 177

164177

165178 Regular text content.

166179

180 - `type: "text"`

181

167182 - `text: string`

168183

169184 The text content.

from line 185

170185

171186 minLength: 1

172187

173 - `type: "text"`

174

175188 - `BetaManagedAgentsImageBlock object`

176189

177190 Image content specified directly as base64 data or as a reference via a URL.

178191

192 - `type: "image"`

193

179194 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`

180195

181196 Union type for image source variants.

from line 199

184199

185200 Base64-encoded image data.

186201

202 - `type: "base64"`

203

187204 - `data: string`

188205

189206 Base64-encoded image data.

from line 213

196213

197214 minLength: 1

198215

199 - `type: "base64"`

200

201216 - `BetaManagedAgentsURLImageSource object`

202217

203218 Image referenced by URL.

from line 229

214229

215230 Image referenced by file ID.

216231

232 - `type: "file"`

233

217234 - `file_id: string`

218235

219236 ID of a previously uploaded file.

from line 237

220237

221238 minLength: 1

222239

223 - `type: "file"`

224

225 - `type: "image"`

226

227240 - `BetaManagedAgentsDocumentBlock object`

228241

229242 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

230243

244 - `type: "document"`

245

231246 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`

232247

233248 Union type for document source variants.

from line 251

236251

237252 Base64-encoded document data.

238253

254 - `type: "base64"`

255

239256 - `data: string`

240257

241258 Base64-encoded document data.

from line 265

248265

249266 minLength: 1

250267

251 - `type: "base64"`

252

253268 - `BetaManagedAgentsPlainTextDocumentSource object`

254269

255270 Plain text document content.

256271

272 - `type: "text"`

273

257274 - `data: string`

258275

259276 The plain text content.

from line 281

264281

265282 MIME type of the text content. Must be "text/plain".

266283

267 - `type: "text"`

268

269284 - `BetaManagedAgentsURLDocumentSource object`

270285

271286 Document referenced by URL.

from line 297

282297

283298 Document referenced by file ID.

284299

300 - `type: "file"`

301

285302 - `file_id: string`

286303

287304 ID of a previously uploaded file.

from line 305

288305

289306 minLength: 1

290307

291 - `type: "file"`

292

293 - `type: "document"`

294

295308 - `context: optional string or null`

296309

297310 Additional context about the document for the model.

from line 319

306319

307320 - `type: "redacted"`

308321

309 - `type: "user.message"`

310

311322 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`

312323

313324 An outcome the agent should work toward. The agent begins work on receipt.

314325

326 - `type: "user.define_outcome"`

327

315328 - `description: string`

316329

317330 What the agent should produce. This is the task specification.

from line 337

324337

325338 Rubric referenced by a file uploaded via the Files API.

326339

340 - `type: "file"`

341

327342 - `file_id: string`

328343

329344 ID of the rubric file.

330345

331 - `type: "file"`

332

333346 - `BetaManagedAgentsTextRubric object`

334347

335348 Rubric content provided inline as text.

336349

350 - `type: "text"`

351

337352 - `content: string`

338353

339354 Rubric content. Plain text or markdown — the grader treats it as freeform text.

340355

341 - `type: "text"`

342

343 - `type: "user.define_outcome"`

344

345356 - `max_iterations: optional number or null`

346357

347358 Eval→revision cycles before giving up. Default 3, max 20.

from line 363

352363

353364 Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt.

354365

366 - `type: "system.message"`

367

355368 - `content: array of BetaManagedAgentsSystemContentBlock`

356369

357370 System content blocks to append. Text-only.

358371

372 - `type: "text"`

373

359374 - `text: string`

360375

361376 The text content.

from line 377

362377

363378 minLength: 1

364379

365 - `type: "text"`

366

367 - `type: "system.message"`

368

369380 - `metadata: map[string]`

370381

371382 Arbitrary key-value metadata. Maximum 16 pairs.

from line 399

388399

389400 A scheduled fire recorded a failed run whose error auto-pauses the deployment.

390401

402 - `type: "error"`

403

391404 - `error: BetaManagedAgentsDeploymentPausedReasonError`

392405

393406 The error that triggered an auto-pause. Matches the failed run's `error.type`.

from line 489

476489

477490 - `type: "mcp_egress_blocked_error"`

478491

479 - `type: "error"`

480

481492 - `resources: array of BetaManagedAgentsSessionResourceConfig`

482493

483494 Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.

from line 509

498509

499510 - `BetaManagedAgentsBranchCheckout object`

500511

512 - `type: "branch"`

513

501514 - `name: string`

502515

503516 Branch name to check out.

from line 517

504517

505518 minLength: 1, maxLength: 255

506519

507 - `type: "branch"`

508

509520 - `BetaManagedAgentsCommitCheckout object`

510521

522 - `type: "commit"`

523

511524 - `sha: string`

512525

513526 Full commit SHA to check out.

from line 527

514527

515528 minLength: 7, maxLength: 64

516529

517 - `type: "commit"`

518

519530 - `mount_path: optional string or null`

520531

521532 Mount path in the container. Defaults to `/workspace/<repo-name>`.

from line 535

524535

525536 A file mounted into each session's container.

526537

538 - `type: "file"`

539

527540 - `file_id: string`

528541

529542 ID of a previously uploaded file.

530543

531 - `type: "file"`

532

533544 - `mount_path: optional string or null`

534545

535546 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

from line 549

538549

539550 A memory store attached to each session created from this deployment.

540551

552 - `type: "memory_store"`

553

541554 - `memory_store_id: string`

542555

543556 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

544557

545 - `type: "memory_store"`

546

547558 - `access: optional "read_write" or "read_only" or null`

548559

549560 Access mode for an attached memory store.

from line 571

560571

561572 5-field POSIX cron schedule with computed runtime timestamps.

562573

574 - `type: "cron"`

575

563576 - `expression: string`

564577

565578 5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).

from line 585

572585

573586 minLength: 1

574587

575 - `type: "cron"`

576

577588 - `last_run_at: optional string or null`

578589

579590 A timestamp in RFC 3339 format

from line 603

592603

593604 - `"paused"`

594605

595 - `type: "deployment"`

596

597606 - `updated_at: string`

598607

599608 A timestamp in RFC 3339 format

from line 617

608617

609618 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.

610619

620 - `type: "limit"`

621

611622 - `max_list_cost: BetaMonetaryAmount`

612623

613624 A monetary amount in a specific currency.

from line 630

619630 - `currency: BetaCurrency`

620631

621632 Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.

622

623 - `type: "limit"`

624633

625634## Example

626635

One read of Claude Developer Platform

What this read moved

api/admin/workspaces/retrieve Page removed · 131 lines, page removed

api/admin/workspaces/service_accounts Page removed · 654 lines, page removed

api/admin/workspaces/service_accounts/create Page removed · 110 lines, page removed

api/admin/workspaces/service_accounts/delete Page removed · 64 lines, page removed

api/admin/workspaces/service_accounts/list Page removed · 108 lines, page removed

api/admin/workspaces/service_accounts/retrieve Page removed · 89 lines, page removed

api/admin/workspaces/service_accounts/update Page removed · 107 lines, page removed

api/admin/workspaces/update Page removed · 194 lines, page removed

api/beta Changed · +33482 / -22540 lines

api/beta/agents Changed · +6319 / -5526 lines

api/beta/agents/archive Changed · +368 / -313 lines

api/beta/agents/create Changed · +994 / -893 lines

api/beta/agents/list Changed · +368 / -313 lines

api/beta/agents/retrieve Changed · +368 / -313 lines

api/beta/agents/update Changed · +1000 / -899 lines

api/beta/agents/versions Changed · +368 / -313 lines

api/beta/agents/versions/list Changed · +368 / -313 lines

api/beta/deployment_runs Changed · +293 / -280 lines

api/beta/deployment_runs/list Changed · +80 / -71 lines

api/beta/deployment_runs/retrieve Changed · +80 / -71 lines

api/beta/deployments Changed · +4428 / -4391 lines

api/beta/deployments/archive Changed · +198 / -189 lines

api/beta/deployments/create Changed · +873 / -864 lines

api/beta/deployments/list Changed · +198 / -189 lines

api/beta/deployments/pause Changed · +198 / -189 lines