List Agent Versions changedapi/beta/agents/versions/list
Nearest release: v2.1.245, published an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+73added
Lines−128removed
From line
1
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits23to this page, all time
# List Agent Versions ## Path parameters ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List Agent Versions ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
The whole hunk
from line 1, old and new numbered
/
from line 1
1---
2title: List Agent Versions
3url: https://platform.claude.com/docs/en/api/beta/agents/versions/list
4---
1# List Agent Versions
52
6## List Agent Versions
3**GET** `/v1/agents/{agent_id}/versions`
74
8**get** `/v1/agents/{agent_id}/versions`
9
105List Agent Versions
116
12### Path Parameters
7## Path parameters
138
149- `agent_id: string`
1510
16### Query Parameters
11## Query parameters
1712
1813- `limit: optional number`
1914
2015 Maximum results per page. Default 20, maximum 100.
2116
17 format: int32
18
2219- `page: optional string`
2320
2421 Opaque pagination cursor.
2522
26### Header Parameters
23## Headers
2724
2825- `"anthropic-beta": optional array of AnthropicBeta`
2926
from line 98
10198
10299 - `"mid-conversation-tool-changes-2026-07-01"`
103100
104### Returns
101## Returns
105102
106103- `data: array of BetaManagedAgentsAgent`
107104
from line 110
113110
114111 A timestamp in RFC 3339 format
115112
113 format: date-time
114
116115 - `created_at: string`
117116
118117 A timestamp in RFC 3339 format
119118
119 format: date-time
120
120121 - `description: string or null`
121122
122123 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
from line 126
125126
126127 - `type: "url"`
127128
128 - `"url"`
129
130129 - `url: string`
131130
132131 - `metadata: map[string]`
from line 204
205204
206205 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
207206
208 - `BetaManagedAgentsEffortLow object { type }`
207 - `BetaManagedAgentsEffortLow object`
209208
210209 Low effort. Favors latency over reasoning depth.
211210
212211 - `type: "low"`
213212
214 - `"low"`
213 - `BetaManagedAgentsEffortMedium object`
215214
216 - `BetaManagedAgentsEffortMedium object { type }`
217
218215 Medium effort. Balances latency and reasoning depth.
219216
220217 - `type: "medium"`
221218
222 - `"medium"`
219 - `BetaManagedAgentsEffortHigh object`
223220
224 - `BetaManagedAgentsEffortHigh object { type }`
225
226221 High effort. Favors reasoning depth.
227222
228223 - `type: "high"`
229224
230 - `"high"`
225 - `BetaManagedAgentsEffortXhigh object`
231226
232 - `BetaManagedAgentsEffortXhigh object { type }`
233
234227 Extra-high effort. Not all models accept this level.
235228
236229 - `type: "xhigh"`
237230
238 - `"xhigh"`
231 - `BetaManagedAgentsEffortMax object`
239232
240 - `BetaManagedAgentsEffortMax object { type }`
241
242233 Maximum effort. Favors reasoning depth over latency.
243234
244235 - `type: "max"`
245236
246 - `"max"`
247
248237 - `inference_geo: optional string`
249238
250239 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 254
265254
266255 Agents the coordinator may spawn as session threads, each resolved to a specific version.
267256
268 - `BetaManagedAgentsAgentReference object { id, type, version }`
257 - `BetaManagedAgentsAgentReference object`
269258
270259 A resolved agent reference with a concrete version.
271260
from line 262
273262
274263 - `type: "agent"`
275264
276 - `"agent"`
277
278265 - `version: number`
279266
280 - `BetaManagedAgentsAdvisor object { model, type }`
267 format: int32
281268
269 - `BetaManagedAgentsAdvisor object`
270
282271 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
283272
284273 - `model: string`
from line 276
287276
288277 - `type: "advisor"`
289278
290 - `"advisor"`
291
292279 - `type: "coordinator"`
293280
294 - `"coordinator"`
295
296281 - `name: string`
297282
298283 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
299284
300 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
285 - `BetaManagedAgentsAnthropicSkill object`
301286
302287 A resolved Anthropic-managed skill.
303288
from line 290
305290
306291 - `type: "anthropic"`
307292
308 - `"anthropic"`
309
310293 - `version: string`
311294
312 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
295 - `BetaManagedAgentsCustomSkill object`
313296
314297 A resolved user-created custom skill.
315298
from line 300
317300
318301 - `type: "custom"`
319302
320 - `"custom"`
321
322303 - `version: string`
323304
324305 - `system: string or null`
from line 306
325306
326307 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
327308
328 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
309 - `BetaManagedAgentsAgentToolset20260401 object`
329310
330311 - `configs: array of BetaManagedAgentsAgentToolConfig`
331312
332 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
313 - `BetaManagedAgentsBashToolConfig object`
333314
334315 Configuration for the bash tool.
335316
from line 318
337318
338319 - `name: "bash"`
339320
340 - `"bash"`
341
342321 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
343322
344323 Permission policy for tool execution.
345324
346 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
325 - `BetaManagedAgentsAlwaysAllowPolicy object`
347326
348327 Tool calls are automatically approved without user confirmation.
349328
350329 - `type: "always_allow"`
351330
352 - `"always_allow"`
331 - `BetaManagedAgentsAlwaysAskPolicy object`
353332
354 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
355
356333 Tool calls require user confirmation before execution.
357334
358335 - `type: "always_ask"`
359336
360 - `"always_ask"`
361
362337 - `type: "bash"`
363338
364 - `"bash"`
339 - `BetaManagedAgentsEditToolConfig object`
365340
366 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
367
368341 Configuration for the edit tool.
369342
370343 - `enabled: boolean`
from line 344
371344
372345 - `name: "edit"`
373346
374 - `"edit"`
375
376347 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
377348
378349 Permission policy for tool execution.
379350
380 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
351 - `BetaManagedAgentsAlwaysAllowPolicy object`
381352
382353 Tool calls are automatically approved without user confirmation.
383354
384 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
355 - `BetaManagedAgentsAlwaysAskPolicy object`
385356
386357 Tool calls require user confirmation before execution.
387358
388359 - `type: "edit"`
389360
390 - `"edit"`
361 - `BetaManagedAgentsReadToolConfig object`
391362
392 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
393
394363 Configuration for the read tool.
395364
396365 - `enabled: boolean`
from line 366
397366
398367 - `name: "read"`
399368
400 - `"read"`
401
402369 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
403370
404371 Permission policy for tool execution.
405372
406 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
373 - `BetaManagedAgentsAlwaysAllowPolicy object`
407374
408375 Tool calls are automatically approved without user confirmation.
409376
410 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
377 - `BetaManagedAgentsAlwaysAskPolicy object`
411378
412379 Tool calls require user confirmation before execution.
413380
414381 - `type: "read"`
415382
416 - `"read"`
383 - `BetaManagedAgentsWriteToolConfig object`
417384
418 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
419
420385 Configuration for the write tool.
421386
422387 - `enabled: boolean`
from line 388
423388
424389 - `name: "write"`
425390
426 - `"write"`
427
428391 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
429392
430393 Permission policy for tool execution.
431394
432 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
395 - `BetaManagedAgentsAlwaysAllowPolicy object`
433396
434397 Tool calls are automatically approved without user confirmation.
435398
436 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
399 - `BetaManagedAgentsAlwaysAskPolicy object`
437400
438401 Tool calls require user confirmation before execution.
439402
440403 - `type: "write"`
441404
442 - `"write"`
405 - `BetaManagedAgentsGlobToolConfig object`
443406
444 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
445
446407 Configuration for the glob tool.
447408
448409 - `enabled: boolean`
from line 410
449410
450411 - `name: "glob"`
451412
452 - `"glob"`
453
454413 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
455414
456415 Permission policy for tool execution.
457416
458 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
417 - `BetaManagedAgentsAlwaysAllowPolicy object`
459418
460419 Tool calls are automatically approved without user confirmation.
461420
462 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
421 - `BetaManagedAgentsAlwaysAskPolicy object`
463422
464423 Tool calls require user confirmation before execution.
465424
466425 - `type: "glob"`
467426
468 - `"glob"`
427 - `BetaManagedAgentsGrepToolConfig object`
469428
470 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
471
472429 Configuration for the grep tool.
473430
474431 - `enabled: boolean`
from line 432
475432
476433 - `name: "grep"`
477434
478 - `"grep"`
479
480435 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
481436
482437 Permission policy for tool execution.
483438
484 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
439 - `BetaManagedAgentsAlwaysAllowPolicy object`
485440
486441 Tool calls are automatically approved without user confirmation.
487442
488 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
443 - `BetaManagedAgentsAlwaysAskPolicy object`
489444
490445 Tool calls require user confirmation before execution.
491446
492447 - `type: "grep"`
493448
494 - `"grep"`
449 - `BetaManagedAgentsWebFetchToolConfig object`
495450
496 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
497
498451 Configuration for the web_fetch tool.
499452
500453 - `enabled: boolean`
from line 454
501454
502455 - `name: "web_fetch"`
503456
504 - `"web_fetch"`
505
506457 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
507458
508459 Permission policy for tool execution.
509460
510 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
461 - `BetaManagedAgentsAlwaysAllowPolicy object`
511462
512463 Tool calls are automatically approved without user confirmation.
513464
514 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
465 - `BetaManagedAgentsAlwaysAskPolicy object`
515466
516467 Tool calls require user confirmation before execution.
517468
518469 - `type: "web_fetch"`
519470
520 - `"web_fetch"`
521
522471 - `allowed_domains: optional array of string`
523472
524473 - `blocked_domains: optional array of string`
from line 474
525474
526475 - `max_content_tokens: optional number or null`
527476
528 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
477 format: int32
529478
479 - `BetaManagedAgentsWebSearchToolConfig object`
480
530481 Configuration for the web_search tool.
531482
532483 - `enabled: boolean`
from line 484
533484
534485 - `name: "web_search"`
535486
536 - `"web_search"`
537
538487 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
539488
540489 Permission policy for tool execution.
541490
542 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
491 - `BetaManagedAgentsAlwaysAllowPolicy object`
543492
544493 Tool calls are automatically approved without user confirmation.
545494
546 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
495 - `BetaManagedAgentsAlwaysAskPolicy object`
547496
548497 Tool calls require user confirmation before execution.
549498
550499 - `type: "web_search"`
551500
552 - `"web_search"`
553
554501 - `allowed_domains: optional array of string`
555502
556503 - `blocked_domains: optional array of string`
from line 510
563510
564511 Location precision. Only "approximate" is supported.
565512
566 - `"approximate"`
567
568513 - `city: optional string or null`
569514
570515 City name.
571516
517 minLength: 1, maxLength: 255
518
572519 - `country: optional string or null`
573520
574521 Two-letter ISO 3166-1 country code, uppercase.
from line 524
577524
578525 Region or state name.
579526
527 minLength: 1, maxLength: 255
528
580529 - `timezone: optional string or null`
581530
582531 IANA timezone identifier, e.g. "America/Los_Angeles".
583532
533 minLength: 1, maxLength: 255
534
584535 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
585536
586537 Resolved default configuration for agent tools.
from line 542
591542
592543 Permission policy for tool execution.
593544
594 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
545 - `BetaManagedAgentsAlwaysAllowPolicy object`
595546
596547 Tool calls are automatically approved without user confirmation.
597548
598 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
549 - `BetaManagedAgentsAlwaysAskPolicy object`
599550
600551 Tool calls require user confirmation before execution.
601552
602553 - `type: "agent_toolset_20260401"`
603554
604 - `"agent_toolset_20260401"`
555 - `BetaManagedAgentsMCPToolset object`
605556
606 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
607
608557 - `configs: array of BetaManagedAgentsMCPToolConfig`
609558
610559 - `enabled: boolean`
from line 564
615564
616565 Permission policy for tool execution.
617566
618 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
567 - `BetaManagedAgentsAlwaysAllowPolicy object`
619568
620569 Tool calls are automatically approved without user confirmation.
621570
622 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
571 - `BetaManagedAgentsAlwaysAskPolicy object`
623572
624573 Tool calls require user confirmation before execution.
625574
from line 582
633582
634583 Permission policy for tool execution.
635584
636 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
585 - `BetaManagedAgentsAlwaysAllowPolicy object`
637586
638587 Tool calls are automatically approved without user confirmation.
639588
640 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
589 - `BetaManagedAgentsAlwaysAskPolicy object`
641590
642591 Tool calls require user confirmation before execution.
643592
from line 594
645594
646595 - `type: "mcp_toolset"`
647596
648 - `"mcp_toolset"`
597 - `BetaManagedAgentsCustomTool object`
649598
650 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
651
652599 A custom tool as returned in API responses.
653600
654601 - `description: string`
from line 606
659606
660607 - `type: "object"`
661608
662 - `"object"`
663
664609 - `properties: optional map[unknown] or null`
665610
666611 - `required: optional array of string or null`
from line 614
669614
670615 - `type: "custom"`
671616
672 - `"custom"`
673
674617 - `type: "agent"`
675618
676 - `"agent"`
677
678619 - `updated_at: string`
679620
680621 A timestamp in RFC 3339 format
681622
623 format: date-time
624
682625 - `version: number`
683626
684627 The agent's current version. Starts at 1 and increments when the agent is modified.
685628
629 format: int32
630
686631- `next_page: optional string or null`
687632
688633 Opaque cursor for the next page. Null when no more results.
689634
690### Example
635## Example
691636
692```http
637```bash
693638curl https://api.anthropic.com/v1/agents/$AGENT_ID/versions \
694639 -H 'anthropic-version: 2023-06-01' \
695640 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 641
696641 -H "X-Api-Key: $ANTHROPIC_API_KEY"
697642```
698643
699#### Response
644### Response (200)
700645
701646```json
702647{
No line in this hunk matches that.