Repository Public
1---2title: Versions3url: https://platform.claude.com/docs/en/api/beta/agents/versions4---56# Versions78## List Agent Versions910**GET** `/v1/agents/{agent_id}/versions`1112List Agent Versions1314### Path parameters1516- `agent_id: string`1718### Query parameters1920- `limit: optional number`2122 Maximum results per page. Default 20, maximum 100.2324 format: int322526- `page: optional string`2728 Opaque pagination cursor.2930### Headers3132- `"anthropic-beta": optional array of AnthropicBeta`3334 Optional header to specify the beta version(s) you want to use.3536 - `string`3738 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more`3940 - `"message-batches-2024-09-24"`4142 - `"prompt-caching-2024-07-31"`4344 - `"computer-use-2024-10-22"`4546 - `"computer-use-2025-01-24"`4748 - `"pdfs-2024-09-25"`4950 - `"token-counting-2024-11-01"`5152 - `"token-efficient-tools-2025-02-19"`5354 - `"output-128k-2025-02-19"`5556 - `"files-api-2025-04-14"`5758 - `"mcp-client-2025-04-04"`5960 - `"mcp-client-2025-11-20"`6162 - `"dev-full-thinking-2025-05-14"`6364 - `"interleaved-thinking-2025-05-14"`6566 - `"code-execution-2025-05-22"`6768 - `"extended-cache-ttl-2025-04-11"`6970 - `"context-1m-2025-08-07"`7172 - `"context-management-2025-06-27"`7374 - `"model-context-window-exceeded-2025-08-26"`7576 - `"skills-2025-10-02"`7778 - `"fast-mode-2026-02-01"`7980 - `"output-300k-2026-03-24"`8182 - `"user-profiles-2026-03-24"`8384 - `"user-profiles-2026-08-18"`8586 - `"user-profiles-2026-09-04"`8788 - `"advisor-tool-2026-03-01"`8990 - `"managed-agents-2026-04-01"`9192 - `"cache-diagnosis-2026-04-07"`9394 - `"dreaming-2026-04-21"`9596 - `"thinking-token-count-2026-05-13"`9798 - `"server-side-fallback-2026-06-01"`99100 - `"server-side-fallback-2026-07-01"`101102 - `"fallback-credit-2026-06-01"`103104 - `"fallback-credit-2026-07-01"`105106 - `"agent-memory-2026-07-22"`107108 - `"mid-conversation-tool-changes-2026-07-01"`109110 - `"compact-2026-01-12"`111112 - `"computer-use-2025-11-24"`113114 - `"mcp-tunnels-2026-06-22"`115116 - `"structured-outputs-2025-11-13"`117118 - `"task-budgets-2026-03-13"`119120 - `"thinking-display-updates-2026-08-18"`121122 - `"ce-user-management-2026-07-13"`123124 - `"mid-conversation-output-config-2026-07-01"`125126 - `"thinking-binding-controls-2026-08-01"`127128 - `"mid-conversation-system-clear-at-2026-08-21"`129130 - `"compact-2026-09-04"`131132- `"anthropic-workspace-id": optional string`133134### Returns135136- `data: array of BetaManagedAgentsAgent`137138 Agent versions.139140 - `type: "agent"`141142 - `id: string`143144 - `archived_at: string or null`145146 A timestamp in RFC 3339 format147148 format: date-time149150 - `created_at: string`151152 A timestamp in RFC 3339 format153154 format: date-time155156 - `description: string or null`157158 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`159160 - `type: "url"`161162 - `name: string`163164 - `url: string`165166 - `metadata: map[string]`167168 - `model: BetaManagedAgentsModelConfig`169170 Model identifier and configuration.171172 - `id: BetaManagedAgentsModel`173174 The model that will power your agent.175176 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.177178 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`179180 The model that will power your agent.181182 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.183184 - `"claude-fable-5-1"`185186 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows187188 - `"claude-sonnet-5"`189190 High-performance model for coding and agents191192 - `"claude-fable-5"`193194 Next generation of intelligence for the hardest knowledge work and coding problems195196 - `"claude-opus-5"`197198 Powerful intelligence for long-running agents and coding199200 - `"claude-opus-4-8"`201202 Powerful intelligence for long-running agents and coding203204 - `"claude-opus-4-7"`205206 Powerful intelligence for long-running agents and coding207208 - `"claude-opus-4-6"`209210 Powerful intelligence for long-running agents and coding211212 - `"claude-sonnet-4-6"`213214 Best combination of speed and intelligence215216 - `"claude-haiku-4-5"`217218 Fastest model with near-frontier intelligence219220 - `"claude-haiku-4-5-20251001"`221222 Fastest model with near-frontier intelligence223224 - `"claude-opus-4-5"`225226 Powerful intelligence for long-running agents and coding227228 - `"claude-opus-4-5-20251101"`229230 Powerful intelligence for long-running agents and coding231232 - `"claude-sonnet-4-5"`233234 High-performance model for agents and coding235236 - `"claude-sonnet-4-5-20250929"`237238 High-performance model for agents and coding239240 - `string`241242 - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more`243244 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.245246 - `BetaManagedAgentsEffortLow object`247248 Low effort. Favors latency over reasoning depth.249250 - `type: "low"`251252 - `BetaManagedAgentsEffortMedium object`253254 Medium effort. Balances latency and reasoning depth.255256 - `type: "medium"`257258 - `BetaManagedAgentsEffortHigh object`259260 High effort. Favors reasoning depth.261262 - `type: "high"`263264 - `BetaManagedAgentsEffortXhigh object`265266 Extra-high effort. Not all models accept this level.267268 - `type: "xhigh"`269270 - `BetaManagedAgentsEffortMax object`271272 Maximum effort. Favors reasoning depth over latency.273274 - `type: "max"`275276 - `inference_geo: optional string`277278 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.279280 - `speed: optional "standard" or "fast"`281282 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.283284 - `"standard"`285286 - `"fast"`287288 - `multiagent: BetaManagedAgentsMultiagent or null`289290 Resolved coordinator topology with a concrete agent roster.291292 - `type: "coordinator"`293294 - `agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor`295296 Agents the coordinator may spawn as session threads, each resolved to a specific version.297298 - `BetaManagedAgentsAgentReference object`299300 A resolved agent reference with a concrete version.301302 - `type: "agent"`303304 - `id: string`305306 - `version: number`307308 format: int32309310 - `BetaManagedAgentsAdvisor object`311312 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.313314 - `type: "advisor"`315316 - `model: string`317318 The advisor model id.319320 - `name: string`321322 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`323324 - `BetaManagedAgentsAnthropicSkill object`325326 A resolved Anthropic-managed skill.327328 - `type: "anthropic"`329330 - `skill_id: string`331332 - `version: string`333334 - `BetaManagedAgentsCustomSkill object`335336 A resolved user-created custom skill.337338 - `type: "custom"`339340 - `skill_id: string`341342 - `version: string`343344 - `system: string or null`345346 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`347348 - `BetaManagedAgentsAgentToolset20260401 object`349350 - `type: "agent_toolset_20260401"`351352 - `configs: array of BetaManagedAgentsAgentToolConfig`353354 - `BetaManagedAgentsBashToolConfig object`355356 Configuration for the bash tool.357358 - `type: "bash"`359360 - `enabled: boolean`361362 - `name: "bash"`363364 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`365366 Permission policy for tool execution.367368 - `BetaManagedAgentsAlwaysAllowPolicy object`369370 Tool calls are automatically approved without user confirmation.371372 - `type: "always_allow"`373374 - `BetaManagedAgentsAlwaysAskPolicy object`375376 Tool calls require user confirmation before execution.377378 - `type: "always_ask"`379380 - `BetaManagedAgentsAutoPolicy object`381382 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.383384 - `type: "auto"`385386 - `BetaManagedAgentsEditToolConfig object`387388 Configuration for the edit tool.389390 - `type: "edit"`391392 - `enabled: boolean`393394 - `name: "edit"`395396 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`397398 Permission policy for tool execution.399400 - `BetaManagedAgentsAlwaysAllowPolicy object`401402 Tool calls are automatically approved without user confirmation.403404 - `BetaManagedAgentsAlwaysAskPolicy object`405406 Tool calls require user confirmation before execution.407408 - `BetaManagedAgentsAutoPolicy object`409410 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.411412 - `BetaManagedAgentsReadToolConfig object`413414 Configuration for the read tool.415416 - `type: "read"`417418 - `enabled: boolean`419420 - `name: "read"`421422 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`423424 Permission policy for tool execution.425426 - `BetaManagedAgentsAlwaysAllowPolicy object`427428 Tool calls are automatically approved without user confirmation.429430 - `BetaManagedAgentsAlwaysAskPolicy object`431432 Tool calls require user confirmation before execution.433434 - `BetaManagedAgentsAutoPolicy object`435436 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.437438 - `BetaManagedAgentsWriteToolConfig object`439440 Configuration for the write tool.441442 - `type: "write"`443444 - `enabled: boolean`445446 - `name: "write"`447448 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`449450 Permission policy for tool execution.451452 - `BetaManagedAgentsAlwaysAllowPolicy object`453454 Tool calls are automatically approved without user confirmation.455456 - `BetaManagedAgentsAlwaysAskPolicy object`457458 Tool calls require user confirmation before execution.459460 - `BetaManagedAgentsAutoPolicy object`461462 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.463464 - `BetaManagedAgentsGlobToolConfig object`465466 Configuration for the glob tool.467468 - `type: "glob"`469470 - `enabled: boolean`471472 - `name: "glob"`473474 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`475476 Permission policy for tool execution.477478 - `BetaManagedAgentsAlwaysAllowPolicy object`479480 Tool calls are automatically approved without user confirmation.481482 - `BetaManagedAgentsAlwaysAskPolicy object`483484 Tool calls require user confirmation before execution.485486 - `BetaManagedAgentsAutoPolicy object`487488 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.489490 - `BetaManagedAgentsGrepToolConfig object`491492 Configuration for the grep tool.493494 - `type: "grep"`495496 - `enabled: boolean`497498 - `name: "grep"`499500 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`501502 Permission policy for tool execution.503504 - `BetaManagedAgentsAlwaysAllowPolicy object`505506 Tool calls are automatically approved without user confirmation.507508 - `BetaManagedAgentsAlwaysAskPolicy object`509510 Tool calls require user confirmation before execution.511512 - `BetaManagedAgentsAutoPolicy object`513514 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.515516 - `BetaManagedAgentsWebFetchToolConfig object`517518 Configuration for the web_fetch tool.519520 - `type: "web_fetch"`521522 - `enabled: boolean`523524 - `name: "web_fetch"`525526 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`527528 Permission policy for tool execution.529530 - `BetaManagedAgentsAlwaysAllowPolicy object`531532 Tool calls are automatically approved without user confirmation.533534 - `BetaManagedAgentsAlwaysAskPolicy object`535536 Tool calls require user confirmation before execution.537538 - `BetaManagedAgentsAutoPolicy object`539540 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.541542 - `allowed_domains: optional array of string`543544 - `blocked_domains: optional array of string`545546 - `max_content_tokens: optional number or null`547548 format: int32549550 - `BetaManagedAgentsWebSearchToolConfig object`551552 Configuration for the web_search tool.553554 - `type: "web_search"`555556 - `enabled: boolean`557558 - `name: "web_search"`559560 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`561562 Permission policy for tool execution.563564 - `BetaManagedAgentsAlwaysAllowPolicy object`565566 Tool calls are automatically approved without user confirmation.567568 - `BetaManagedAgentsAlwaysAskPolicy object`569570 Tool calls require user confirmation before execution.571572 - `BetaManagedAgentsAutoPolicy object`573574 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.575576 - `allowed_domains: optional array of string`577578 - `blocked_domains: optional array of string`579580 - `user_location: optional BetaManagedAgentsUserLocation or null`581582 Approximate user location for search result localization.583584 - `type: "approximate"`585586 Location precision. Only "approximate" is supported.587588 - `city: optional string or null`589590 City name.591592 minLength: 1, maxLength: 255593594 - `country: optional string or null`595596 Two-letter ISO 3166-1 country code, uppercase.597598 - `region: optional string or null`599600 Region or state name.601602 minLength: 1, maxLength: 255603604 - `timezone: optional string or null`605606 IANA timezone identifier, e.g. "America/Los_Angeles".607608 minLength: 1, maxLength: 255609610 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`611612 Resolved default configuration for agent tools.613614 - `enabled: boolean`615616 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`617618 Permission policy for tool execution.619620 - `BetaManagedAgentsAlwaysAllowPolicy object`621622 Tool calls are automatically approved without user confirmation.623624 - `BetaManagedAgentsAlwaysAskPolicy object`625626 Tool calls require user confirmation before execution.627628 - `BetaManagedAgentsAutoPolicy object`629630 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.631632 - `BetaManagedAgentsMCPToolset object`633634 - `type: "mcp_toolset"`635636 - `configs: array of BetaManagedAgentsMCPToolConfig`637638 - `enabled: boolean`639640 - `name: string`641642 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`643644 Permission policy for tool execution.645646 - `BetaManagedAgentsAlwaysAllowPolicy object`647648 Tool calls are automatically approved without user confirmation.649650 - `BetaManagedAgentsAlwaysAskPolicy object`651652 Tool calls require user confirmation before execution.653654 - `BetaManagedAgentsAutoPolicy object`655656 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.657658 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`659660 Resolved default configuration for all tools from an MCP server.661662 - `enabled: boolean`663664 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`665666 Permission policy for tool execution.667668 - `BetaManagedAgentsAlwaysAllowPolicy object`669670 Tool calls are automatically approved without user confirmation.671672 - `BetaManagedAgentsAlwaysAskPolicy object`673674 Tool calls require user confirmation before execution.675676 - `BetaManagedAgentsAutoPolicy object`677678 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.679680 - `mcp_server_name: string`681682 - `BetaManagedAgentsCustomTool object`683684 A custom tool as returned in API responses.685686 - `type: "custom"`687688 - `description: string`689690 - `input_schema: BetaManagedAgentsCustomToolInputSchema`691692 JSON Schema for custom tool input parameters.693694 - `type: "object"`695696 - `properties: optional map[unknown] or null`697698 - `required: optional array of string or null`699700 - `name: string`701702 - `updated_at: string`703704 A timestamp in RFC 3339 format705706 format: date-time707708 - `version: number`709710 The agent's current version. Starts at 1 and increments when the agent is modified.711712 format: int32713714- `next_page: optional string or null`715716 Opaque cursor for the next page. Null when no more results.717718### Example719720```bash721curl https://api.anthropic.com/v1/agents/$AGENT_ID/versions \722 -H 'anthropic-version: 2023-06-01' \723 -H 'anthropic-beta: managed-agents-2026-04-01' \724 -H "X-Api-Key: $ANTHROPIC_API_KEY"725```726727#### Response (200)728729```json730{731 "data": [732 {733 "id": "agent_011CZkYpogX7uDKUyvBTophP",734 "archived_at": null,735 "created_at": "2026-03-15T10:00:00Z",736 "description": "A general-purpose starter agent.",737 "mcp_servers": [738 {739 "name": "example-mcp",740 "type": "url",741 "url": "https://example-server.modelcontextprotocol.io/sse"742 }743 ],744 "metadata": {745 "foo": "bar"746 },747 "model": {748 "id": "claude-opus-5",749 "effort": {750 "type": "low"751 },752 "inference_geo": "inference_geo",753 "speed": "standard"754 },755 "multiagent": {756 "agents": [757 {758 "id": "agent_011CZkYqphY8vELVzwCUpqiQ",759 "type": "agent",760 "version": 1761 }762 ],763 "type": "coordinator"764 },765 "name": "My First Agent",766 "skills": [767 {768 "skill_id": "xlsx",769 "type": "anthropic",770 "version": "1"771 },772 {773 "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",774 "type": "custom",775 "version": "2"776 }777 ],778 "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",779 "tools": [780 {781 "configs": [782 {783 "enabled": true,784 "name": "bash",785 "permission_policy": {786 "type": "always_allow"787 },788 "type": "bash"789 }790 ],791 "default_config": {792 "enabled": true,793 "permission_policy": {794 "type": "always_ask"795 }796 },797 "type": "agent_toolset_20260401"798 }799 ],800 "type": "agent",801 "updated_at": "2026-03-15T10:00:00Z",802 "version": 1803 }804 ],805 "next_page": "next_page"806}807```808