One read of Claude Developer Platformapi-20260825T033708Z
377 pages moved out of 612 read.
Pages moved
377
significant first
Pages read
612
in this capture
Captured
03:37 UTC
Corpus hash
7d98cae5bb87
corpus-hash
What this read moved
126-150 of 377, page 6 of 16This capture is too large to show at once. Changes 126-150 of 377 are below, significant first; the rest are on the following screens.
api/admin/workspaces/retrieve Changed · +14 / -17 lines
# Get Workspace ## Path parameters ## Returns ## Example ### Response (200) ## Get Workspace ### Path Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Get Workspace
3url: https://platform.claude.com/docs/en/api/admin/workspaces/retrieve
4---
1# Get Workspace
52
6## Get Workspace
3**GET** `/v1/organizations/workspaces/{workspace_id}`
74
8**get** `/v1/organizations/workspaces/{workspace_id}`
9
105Get Workspace
116
12### Path Parameters
7## Path parameters
138
149- `workspace_id: string`
1510
1611 ID of the Workspace.
1712
18### Returns
13## Returns
1914
20- `Workspace object { id, archived_at, compartment_id, 7 more }`
15- `Workspace object`
2116
2217 - `id: string`
2318
from line 22
2722
2823 RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
2924
25 format: date-time
26
3027 - `compartment_id: string`
3128
3229 Identifier for this Workspace's encryption compartment. When you configure a
from line 37
4037
4138 RFC 3339 datetime string indicating when the Workspace was created.
4239
43 - `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
40 format: date-time
4441
42 - `data_residency: object`
43
4544 Data residency configuration.
4645
4746 - `allowed_inference_geos: array of string or "unrestricted"`
from line 51
5251
5352 - `"unrestricted"`
5453
55 - `"unrestricted"`
56
5754 - `default_inference_geo: string`
5855
5956 Default inference geo applied when requests omit the parameter.
from line 87
9087
9188 For Workspaces, this is always `"workspace"`.
9289
93 - `"workspace"`
90 default: workspace
9491
95### Example
92## Example
9693
97```http
94```bash
9895curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID \
9996 -H 'anthropic-version: 2023-06-01' \
10097 -H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
10198```
10299
103#### Response
100### Response (200)
104101
105102```json
106103{
api/admin/workspaces/service_accounts Changed · +47 / -50 lines
### Path parameters ### Headers ### Body parameters #### Response (200) ### Path parameters ### Headers #### Response (200) ### Path parameters ### Query parameters ### Headers #### Response (200) ### Path parameters ### Headers ### Body parameters #### Response (200) ### Path parameters ### Headers #### Response (200) ## Domain types ### Path Parameters ### Header Parameters ### Body Parameters #### Response ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters ### Body Parameters #### Response ### Path Parameters ### Header Parameters #### Response ## Domain Types
from line 1
1---
2title: Service Accounts
3url: https://platform.claude.com/docs/en/api/admin/workspaces/service_accounts
4---
5
61# Service Accounts
72
83## Create Service Account Workspace Member
94
10**post** `/v1/organizations/workspaces/{workspace_id}/service_accounts`
5**POST** `/v1/organizations/workspaces/{workspace_id}/service_accounts`
116
127Add a service account to a workspace with the given `workspace_role`.
138
from line 16
2116accounts cannot be added and are rejected. Requires an OAuth bearer or
2217Console session; Admin API keys are not accepted.
2318
24### Path Parameters
19### Path parameters
2520
2621- `workspace_id: string`
2722
2823 ID of the workspace.
2924
30### Header Parameters
25### Headers
3126
3227- `"anthropic-beta": optional array of string`
3328
from line 30
3530
3631 To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
3732
38### Body Parameters
33### Body parameters
3934
4035- `service_account_id: string`
4136
from line 64
6964
7065- `type: "service_account_workspace_member"`
7166
72 - `"service_account_workspace_member"`
67 default: service_account_workspace_member
7368
7469- `workspace_id: string`
7570
from line 86
9186
9287### Example
9388
94```http
89```bash
9590curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/service_accounts \
9691 -H 'Content-Type: application/json' \
9792 -H 'anthropic-version: 2023-06-01' \
from line 97
10297 }'
10398```
10499
105#### Response
100#### Response (200)
106101
107102```json
108103{
from line 112
117112
118113## Get Service Account Workspace Member
119114
120**get** `/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}`
115**GET** `/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}`
121116
122117Retrieve a service account's membership in a workspace.
123118
from line 123
128123membership is returned with its assigned role. An archived service
129124account returns 404.
130125
131### Path Parameters
126### Path parameters
132127
133128- `workspace_id: string`
134129
from line 133
138133
139134 ID of the service account.
140135
141### Header Parameters
136### Headers
142137
143138- `"anthropic-beta": optional array of string`
144139
from line 157
162157
163158- `type: "service_account_workspace_member"`
164159
165 - `"service_account_workspace_member"`
160 default: service_account_workspace_member
166161
167162- `workspace_id: string`
168163
from line 179
184179
185180### Example
186181
187```http
182```bash
188183curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/service_accounts/$SERVICE_ACCOUNT_ID \
189184 -H 'anthropic-version: 2023-06-01' \
190185 -H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
191186```
192187
193#### Response
188#### Response (200)
194189
195190```json
196191{
from line 200
205200
206201## List Service Account Workspace Members
207202
208**get** `/v1/organizations/workspaces/{workspace_id}/service_accounts`
203**GET** `/v1/organizations/workspaces/{workspace_id}/service_accounts`
209204
210205List the service accounts that are members of a workspace.
211206
from line 211
216211included in this list. Memberships of archived service accounts are
217212omitted from the results.
218213
219### Path Parameters
214### Path parameters
220215
221216- `workspace_id: string`
222217
223218 ID of the workspace.
224219
225### Query Parameters
220### Query parameters
226221
227222- `limit: optional number`
228223
229224 Number of results per page.
230225
226 default: 20, maximum: 100, minimum: 1
227
231228- `page: optional string`
232229
233230 Opaque cursor from a previous response's `next_page`.
234231
235### Header Parameters
232### Headers
236233
237234- `"anthropic-beta": optional array of string`
238235
from line 239
242239
243240### Returns
244241
245- `data: array of object { created_by_actor_id, implicit, service_account_id, 3 more }`
242- `data: array of object`
246243
247244 - `created_by_actor_id: string or null`
248245
from line 255
258255
259256 - `type: "service_account_workspace_member"`
260257
261 - `"service_account_workspace_member"`
258 default: service_account_workspace_member
262259
263260 - `workspace_id: string`
264261
from line 281
284281
285282### Example
286283
287```http
284```bash
288285curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/service_accounts \
289286 -H 'anthropic-version: 2023-06-01' \
290287 -H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
291288```
292289
293#### Response
290#### Response (200)
294291
295292```json
296293{
from line 307
310307
311308## Update Service Account Workspace Member
312309
313**post** `/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}`
310**POST** `/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}`
314311
315312Change a service account's role in a workspace.
316313
from line 319
322319rejected. Requires an OAuth bearer or Console session; Admin API keys
323320are not accepted.
324321
325### Path Parameters
322### Path parameters
326323
327324- `workspace_id: string`
328325
from line 329
332329
333330 ID of the service account.
334331
335### Header Parameters
332### Headers
336333
337334- `"anthropic-beta": optional array of string`
338335
from line 337
340337
341338 To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
342339
343### Body Parameters
340### Body parameters
344341
345342- `workspace_role: "workspace_admin" or "workspace_developer" or "workspace_restricted_developer" or "workspace_user"`
346343
from line 367
370367
371368- `type: "service_account_workspace_member"`
372369
373 - `"service_account_workspace_member"`
370 default: service_account_workspace_member
374371
375372- `workspace_id: string`
376373
from line 389
392389
393390### Example
394391
395```http
392```bash
396393curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/service_accounts/$SERVICE_ACCOUNT_ID \
397394 -H 'Content-Type: application/json' \
398395 -H 'anthropic-version: 2023-06-01' \
from line 399
402399 }'
403400```
404401
405#### Response
402#### Response (200)
406403
407404```json
408405{
from line 414
417414
418415## Delete Service Account Workspace Member
419416
420**delete** `/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}`
417**DELETE** `/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}`
421418
422419Remove a service account from a workspace.
423420
from line 425
428425membership. Archived workspaces return 400. Requires an OAuth bearer or
429426Console session; Admin API keys are not accepted.
430427
431### Path Parameters
428### Path parameters
432429
433430- `workspace_id: string`
434431
from line 435
438435
439436 ID of the service account.
440437
441### Header Parameters
438### Headers
442439
443440- `"anthropic-beta": optional array of string`
444441
from line 451
454451
455452- `type: "service_account_workspace_member_deleted"`
456453
457 - `"service_account_workspace_member_deleted"`
454 default: service_account_workspace_member_deleted
458455
459456- `workspace_id: string`
460457
from line 459
462459
463460### Example
464461
465```http
462```bash
466463curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/service_accounts/$SERVICE_ACCOUNT_ID \
467464 -X DELETE \
468465 -H 'anthropic-version: 2023-06-01' \
from line 466
469466 -H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
470467```
471468
472#### Response
469#### Response (200)
473470
474471```json
475472{
from line 476
479476}
480477```
481478
482## Domain Types
479## Domain types
483480
484481### Service Account Create Response
485482
486- `ServiceAccountCreateResponse object { created_by_actor_id, implicit, service_account_id, 3 more }`
483- `ServiceAccountCreateResponse object`
487484
488485 - `created_by_actor_id: string or null`
489486
from line 496
499496
500497 - `type: "service_account_workspace_member"`
501498
502 - `"service_account_workspace_member"`
499 default: service_account_workspace_member
503500
504501 - `workspace_id: string`
505502
from line 518
521518
522519### Service Account Retrieve Response
523520
524- `ServiceAccountRetrieveResponse object { created_by_actor_id, implicit, service_account_id, 3 more }`
521- `ServiceAccountRetrieveResponse object`
525522
526523 - `created_by_actor_id: string or null`
527524
from line 534
537534
538535 - `type: "service_account_workspace_member"`
539536
540 - `"service_account_workspace_member"`
537 default: service_account_workspace_member
541538
542539 - `workspace_id: string`
543540
from line 556
559556
560557### Service Account List Response
561558
562- `ServiceAccountListResponse object { created_by_actor_id, implicit, service_account_id, 3 more }`
559- `ServiceAccountListResponse object`
563560
564561 - `created_by_actor_id: string or null`
565562
from line 572
575572
576573 - `type: "service_account_workspace_member"`
577574
578 - `"service_account_workspace_member"`
575 default: service_account_workspace_member
579576
580577 - `workspace_id: string`
581578
from line 594
597594
598595### Service Account Update Response
599596
600- `ServiceAccountUpdateResponse object { created_by_actor_id, implicit, service_account_id, 3 more }`
597- `ServiceAccountUpdateResponse object`
601598
602599 - `created_by_actor_id: string or null`
603600
from line 610
613610
614611 - `type: "service_account_workspace_member"`
615612
616 - `"service_account_workspace_member"`
613 default: service_account_workspace_member
617614
618615 - `workspace_id: string`
619616
from line 632
635632
636633### Service Account Delete Response
637634
638- `ServiceAccountDeleteResponse object { service_account_id, type, workspace_id }`
635- `ServiceAccountDeleteResponse object`
639636
640637 - `service_account_id: string`
641638
from line 640
643640
644641 - `type: "service_account_workspace_member_deleted"`
645642
646 - `"service_account_workspace_member_deleted"`
643 default: service_account_workspace_member_deleted
647644
648645 - `workspace_id: string`
649646
api/admin/workspaces/service_accounts/create Changed · +10 / -15 lines
# Create Service Account Workspace Member ## Path parameters ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Create Service Account Workspace Member ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Create Service Account Workspace Member
3url: https://platform.claude.com/docs/en/api/admin/workspaces/service_accounts/create
4---
1# Create Service Account Workspace Member
52
6## Create Service Account Workspace Member
3**POST** `/v1/organizations/workspaces/{workspace_id}/service_accounts`
74
8**post** `/v1/organizations/workspaces/{workspace_id}/service_accounts`
9
105Add a service account to a workspace with the given `workspace_role`.
116
127The role determines what the service account can do in the workspace and
from line 14
1914accounts cannot be added and are rejected. Requires an OAuth bearer or
2015Console session; Admin API keys are not accepted.
2116
22### Path Parameters
17## Path parameters
2318
2419- `workspace_id: string`
2520
2621 ID of the workspace.
2722
28### Header Parameters
23## Headers
2924
3025- `"anthropic-beta": optional array of string`
3126
from line 28
3328
3429 To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
3530
36### Body Parameters
31## Body parameters
3732
3833- `service_account_id: string`
3934
from line 46
5146
5247 - `"workspace_user"`
5348
54### Returns
49## Returns
5550
5651- `created_by_actor_id: string or null`
5752
from line 62
6762
6863- `type: "service_account_workspace_member"`
6964
70 - `"service_account_workspace_member"`
65 default: service_account_workspace_member
7166
7267- `workspace_id: string`
7368
from line 82
8782
8883 - `"workspace_user"`
8984
90### Example
85## Example
9186
92```http
87```bash
9388curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/service_accounts \
9489 -H 'Content-Type: application/json' \
9590 -H 'anthropic-version: 2023-06-01' \
from line 95
10095 }'
10196```
10297
103#### Response
98### Response (200)
10499
105100```json
106101{
api/admin/workspaces/service_accounts/delete Changed · +9 / -14 lines
# Delete Service Account Workspace Member ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Delete Service Account Workspace Member ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Delete Service Account Workspace Member
3url: https://platform.claude.com/docs/en/api/admin/workspaces/service_accounts/delete
4---
1# Delete Service Account Workspace Member
52
6## Delete Service Account Workspace Member
3**DELETE** `/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}`
74
8**delete** `/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}`
9
105Remove a service account from a workspace.
116
127Removal is idempotent (returns 200 even if the membership was already
from line 11
1611membership. Archived workspaces return 400. Requires an OAuth bearer or
1712Console session; Admin API keys are not accepted.
1813
19### Path Parameters
14## Path parameters
2015
2116- `workspace_id: string`
2217
from line 21
2621
2722 ID of the service account.
2823
29### Header Parameters
24## Headers
3025
3126- `"anthropic-beta": optional array of string`
3227
from line 29
3429
3530 To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
3631
37### Returns
32## Returns
3833
3934- `service_account_id: string`
4035
from line 37
4237
4338- `type: "service_account_workspace_member_deleted"`
4439
45 - `"service_account_workspace_member_deleted"`
40 default: service_account_workspace_member_deleted
4641
4742- `workspace_id: string`
4843
4944 Tagged workspace ID (`wrkspc_...`) named in the delete request.
5045
51### Example
46## Example
5247
53```http
48```bash
5449curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/service_accounts/$SERVICE_ACCOUNT_ID \
5550 -X DELETE \
5651 -H 'anthropic-version: 2023-06-01' \
from line 52
5752 -H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
5853```
5954
60#### Response
55### Response (200)
6156
6257```json
6358{
api/admin/workspaces/service_accounts/list Changed · +13 / -16 lines
# List Service Account Workspace Members ## Path parameters ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List Service Account Workspace Members ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: List Service Account Workspace Members
3url: https://platform.claude.com/docs/en/api/admin/workspaces/service_accounts/list
4---
1# List Service Account Workspace Members
52
6## List Service Account Workspace Members
3**GET** `/v1/organizations/workspaces/{workspace_id}/service_accounts`
74
8**get** `/v1/organizations/workspaces/{workspace_id}/service_accounts`
9
105List the service accounts that are members of a workspace.
116
127Each entry includes the service account's `workspace_role`. Use `limit`
from line 11
1611included in this list. Memberships of archived service accounts are
1712omitted from the results.
1813
19### Path Parameters
14## Path parameters
2015
2116- `workspace_id: string`
2217
2318 ID of the workspace.
2419
25### Query Parameters
20## Query parameters
2621
2722- `limit: optional number`
2823
2924 Number of results per page.
3025
26 default: 20, maximum: 100, minimum: 1
27
3128- `page: optional string`
3229
3330 Opaque cursor from a previous response's `next_page`.
3431
35### Header Parameters
32## Headers
3633
3734- `"anthropic-beta": optional array of string`
3835
from line 37
4037
4138 To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
4239
43### Returns
40## Returns
4441
45- `data: array of object { created_by_actor_id, implicit, service_account_id, 3 more }`
42- `data: array of object`
4643
4744 - `created_by_actor_id: string or null`
4845
from line 55
5855
5956 - `type: "service_account_workspace_member"`
6057
61 - `"service_account_workspace_member"`
58 default: service_account_workspace_member
6259
6360 - `workspace_id: string`
6461
from line 79
8279
8380 Opaque cursor for the next page, or null if no more results.
8481
85### Example
82## Example
8683
87```http
84```bash
8885curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/service_accounts \
8986 -H 'anthropic-version: 2023-06-01' \
9087 -H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
9188```
9289
93#### Response
90### Response (200)
9491
9592```json
9693{
api/admin/workspaces/service_accounts/retrieve Changed · +9 / -14 lines
# Get Service Account Workspace Member ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Get Service Account Workspace Member ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Get Service Account Workspace Member
3url: https://platform.claude.com/docs/en/api/admin/workspaces/service_accounts/retrieve
4---
1# Get Service Account Workspace Member
52
6## Get Service Account Workspace Member
3**GET** `/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}`
74
8**get** `/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}`
9
105Retrieve a service account's membership in a workspace.
116
127Returns the membership record, including the service account's
from line 11
1611membership is returned with its assigned role. An archived service
1712account returns 404.
1813
19### Path Parameters
14## Path parameters
2015
2116- `workspace_id: string`
2217
from line 21
2621
2722 ID of the service account.
2823
29### Header Parameters
24## Headers
3025
3126- `"anthropic-beta": optional array of string`
3227
from line 29
3429
3530 To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
3631
37### Returns
32## Returns
3833
3934- `created_by_actor_id: string or null`
4035
from line 45
5045
5146- `type: "service_account_workspace_member"`
5247
53 - `"service_account_workspace_member"`
48 default: service_account_workspace_member
5449
5550- `workspace_id: string`
5651
from line 65
7065
7166 - `"workspace_user"`
7267
73### Example
68## Example
7469
75```http
70```bash
7671curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/service_accounts/$SERVICE_ACCOUNT_ID \
7772 -H 'anthropic-version: 2023-06-01' \
7873 -H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
7974```
8075
81#### Response
76### Response (200)
8277
8378```json
8479{
api/admin/workspaces/service_accounts/update Changed · +10 / -15 lines
# Update Service Account Workspace Member ## Path parameters ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Update Service Account Workspace Member ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Update Service Account Workspace Member
3url: https://platform.claude.com/docs/en/api/admin/workspaces/service_accounts/update
4---
1# Update Service Account Workspace Member
52
6## Update Service Account Workspace Member
3**POST** `/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}`
74
8**post** `/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}`
9
105Change a service account's role in a workspace.
116
127The new `workspace_role` replaces the current one. Only explicit
from line 12
1712rejected. Requires an OAuth bearer or Console session; Admin API keys
1813are not accepted.
1914
20### Path Parameters
15## Path parameters
2116
2217- `workspace_id: string`
2318
from line 22
2722
2823 ID of the service account.
2924
30### Header Parameters
25## Headers
3126
3227- `"anthropic-beta": optional array of string`
3328
from line 30
3530
3631 To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
3732
38### Body Parameters
33## Body parameters
3934
4035- `workspace_role: "workspace_admin" or "workspace_developer" or "workspace_restricted_developer" or "workspace_user"`
4136
from line 44
4944
5045 - `"workspace_user"`
5146
52### Returns
47## Returns
5348
5449- `created_by_actor_id: string or null`
5550
from line 60
6560
6661- `type: "service_account_workspace_member"`
6762
68 - `"service_account_workspace_member"`
63 default: service_account_workspace_member
6964
7065- `workspace_id: string`
7166
from line 80
8580
8681 - `"workspace_user"`
8782
88### Example
83## Example
8984
90```http
85```bash
9186curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/service_accounts/$SERVICE_ACCOUNT_ID \
9287 -H 'Content-Type: application/json' \
9388 -H 'anthropic-version: 2023-06-01' \
from line 92
9792 }'
9893```
9994
100#### Response
95### Response (200)
10196
10297```json
10398{
api/admin/workspaces/update Changed · +18 / -21 lines
# Update Workspace ## Path parameters ## Body parameters ## Returns ## Example ### Response (200) ## Update Workspace ### Path Parameters ### Body Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Update Workspace
3url: https://platform.claude.com/docs/en/api/admin/workspaces/update
4---
1# Update Workspace
52
6## Update Workspace
3**POST** `/v1/organizations/workspaces/{workspace_id}`
74
8**post** `/v1/organizations/workspaces/{workspace_id}`
9
105Update Workspace
116
12### Path Parameters
7## Path parameters
138
149- `workspace_id: string`
1510
16### Body Parameters
11## Body parameters
1712
18- `data_residency: optional object { allowed_inference_geos, default_inference_geo } or null`
13- `data_residency: optional object or null`
1914
2015 Data residency configuration for the workspace.
2116
from line 26
3126
3227 - `"unrestricted"`
3328
34 - `"unrestricted"`
35
3629 - `default_inference_geo: optional "global" or "us" or null`
3730
3831 Default inference geo applied when requests omit the parameter. Must be a member of allowed_inference_geos unless allowed_inference_geos is `"unrestricted"`.
from line 48
5548
5649 Name of the Workspace.
5750
51 maxLength: 40, minLength: 1
52
5853- `tags: optional map[string] or null`
5954
6055 User-defined tags as string key-value pairs. Keys may not begin with `anthropic`.
6156
62### Returns
57## Returns
6358
64- `Workspace object { id, archived_at, compartment_id, 7 more }`
59- `Workspace object`
6560
6661 - `id: string`
6762
from line 66
7166
7267 RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
7368
69 format: date-time
70
7471 - `compartment_id: string`
7572
7673 Identifier for this Workspace's encryption compartment. When you configure a
from line 81
8481
8582 RFC 3339 datetime string indicating when the Workspace was created.
8683
87 - `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
84 format: date-time
8885
86 - `data_residency: object`
87
8988 Data residency configuration.
9089
9190 - `allowed_inference_geos: array of string or "unrestricted"`
from line 95
9695
9796 - `"unrestricted"`
9897
99 - `"unrestricted"`
100
10198 - `default_inference_geo: string`
10299
103100 Default inference geo applied when requests omit the parameter.
from line 131
134131
135132 For Workspaces, this is always `"workspace"`.
136133
137 - `"workspace"`
134 default: workspace
138135
139### Example
136## Example
140137
141```http
138```bash
142139curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID \
143140 -H 'Content-Type: application/json' \
144141 -H 'anthropic-version: 2023-06-01' \
from line 149
152149 }'
153150```
154151
155#### Response
152### Response (200)
156153
157154```json
158155{
api/beta Changed · +17191 / -80007 lines
## Domain types ## Beta › Models ### List Models #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Get a Model #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Messages ### Create a Message #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Count tokens in a Message #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ## Beta › Messages › Batches ### Create a Message Batch #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Retrieve a Message Batch #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### List Message Batches #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Cancel a Message Batch #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Delete a Message Batch #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Retrieve Message Batch results #### Path parameters #### Headers #### Returns #### Example ## Beta › Agents ### Create Agent #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### List Agents #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Get Agent #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Update Agent #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Archive Agent #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Agents › Versions ### List Agent Versions #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Environments ### Create Environment #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### List Environments #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Get Environment #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Update Environment #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Delete Environment #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Archive Environment #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Environments › Work ### Get Work Item #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Poll for Work #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Acknowledge Work #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Record Heartbeat #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Stop Work #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### List Work Items #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Update Work Item #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Get Queue Statistics #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Sessions ### Create Session #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### List Sessions #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Get Session #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Update Session #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Delete Session #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Archive Session #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Sessions › Events ### List Events #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Send Events #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Stream Events #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Sessions › Resources ### Add Session Resource #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### List Session Resources #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Get Session Resource #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Update Session Resource #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Delete Session Resource #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Sessions › Threads ### List Session Threads #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Get Session Thread #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Archive Session Thread #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Sessions › Threads › Events ### List Session Thread Events #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Stream Session Thread Events #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Deployments ### Create Deployment #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### List Deployments #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Get Deployment #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Update Deployment #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Archive Deployment #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Run Deployment Now #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Pause Deployment #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Unpause Deployment #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Deployment Runs ### List Deployment Runs #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Get Deployment Run #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Vaults ### Create Vault #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### List Vaults #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Get Vault #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Update Vault #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Delete Vault #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Archive Vault #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Vaults › Credentials ### Create Credential #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### List Credentials #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Get Credential #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Update Credential #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Delete Credential #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Archive Credential #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Validate Credential #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Memory Stores ### Create a memory store #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### List memory stores #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Retrieve a memory store #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Update a memory store #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Delete a memory store #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Archive a memory store #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Memory Stores › Memories ### Create a memory #### Path parameters #### Query parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### List memories #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Retrieve a memory #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Update a memory #### Path parameters #### Query parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Delete a memory #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Memory Stores › Memory Versions ### List memory versions #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Retrieve a memory version #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Redact a memory version #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Files ### Upload File #### Headers #### Body parameters (form-data) #### Returns #### Example ##### Response (200) ### List Files #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Download File #### Path parameters #### Headers #### Example ### Get File Metadata #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Delete File #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Skills ### Create Skill #### Headers #### Body parameters (form-data) #### Returns #### Example ##### Response (200) ### List Skills #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Get Skill #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Delete Skill #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Skills › Versions ### Create Skill Version #### Path parameters #### Headers #### Body parameters (form-data) #### Returns #### Example ##### Response (200) ### List Skill Versions #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Download Skill Version Content #### Path parameters #### Headers #### Example ### Get Skill Version #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Delete Skill Version #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Webhooks ### Unwrap ## Beta › User Profiles ### Create User Profile #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### List User Profiles #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Get User Profile #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Update User Profile #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Create Enrollment URL #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Dreams ### Create a Dream #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### List Dreams #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Get a Dream #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Cancel a Dream #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Archive a Dream #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Beta › Tunnels ### Create Tunnel #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Get Tunnel #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### List Tunnels #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Archive Tunnel #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Reveal Tunnel Token #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Rotate Tunnel Token #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ## Beta › Tunnels › Certificates ### Create Tunnel Certificate #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Get Tunnel Certificate #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### List Tunnel Certificates #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Archive Tunnel Certificate #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Domain Types # Models ## List Models ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Get a Model ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Capability Support ### Beta Context Management Capability ### Beta Effort Capability ### Beta Model Capabilities ### Beta Model Info ### Beta Thinking Capability ### Beta Thinking Types # Messages ## Create a Message ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Count tokens in a Message ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Advisor Message Iteration Usage ### Beta Advisor Redacted Result Block ### Beta Advisor Redacted Result Block Param ### Beta Advisor Result Block ### Beta Advisor Result Block Param ### Beta Advisor Tool 20260301 ### Beta Advisor Tool Result Block ### Beta Advisor Tool Result Block Param ### Beta Advisor Tool Result Error ### Beta Advisor Tool Result Error Param ### Beta All Thinking Turns ### Beta Base64 Image Source ### Beta Base64 PDF Source ### Beta Bash Code Execution Output Block ### Beta Bash Code Execution Output Block Param ### Beta Bash Code Execution Result Block ### Beta Bash Code Execution Result Block Param ### Beta Bash Code Execution Tool Result Block ### Beta Bash Code Execution Tool Result Block Param ### Beta Bash Code Execution Tool Result Error ### Beta Bash Code Execution Tool Result Error Param ### Beta Browser Close Tab Config ### Beta Browser Double Click Config ### Beta Browser File Upload Config ### Beta Browser Find Config ### Beta Browser Form Input Config ### Beta Browser Get Page Text Config ### Beta Browser Hold Key Config ### Beta Browser Hover Config ### Beta Browser Javascript Exec Config ### Beta Browser Key Config ### Beta Browser Left Click Config ### Beta Browser Left Click Drag Config ### Beta Browser Left Mouse Down Config ### Beta Browser Left Mouse Up Config ### Beta Browser List Tabs Config ### Beta Browser Middle Click Config ### Beta Browser Mouse Move Config ### Beta Browser Navigate Config ### Beta Browser New Tab Config ### Beta Browser Read Console Config ### Beta Browser Read Network Config ### Beta Browser Read Page Config ### Beta Browser Right Click Config ### Beta Browser Screenshot Config ### Beta Browser Scroll Config ### Beta Browser Scroll To Config ### Beta Browser State Block Param ### Beta Browser State Change ### Beta Browser State Change Download Completed ### Beta Browser State Change Download Failed ### Beta Browser State Change Download Started ### Beta Browser State Change Tab Opened ### Beta Browser State Tab Entry ### Beta Browser Switch Tab Config ### Beta Browser Toolset 20260801 ### Beta Browser Toolset Configs ### Beta Browser Triple Click Config ### Beta Browser Type Config ### Beta Browser Wait Config ### Beta Browser Zoom Config ### Beta Cache Control Ephemeral ### Beta Cache Creation ### Beta Cache Miss Messages Changed ### Beta Cache Miss Model Changed ### Beta Cache Miss Previous Message Not Found ### Beta Cache Miss System Changed ### Beta Cache Miss Tools Changed ### Beta Cache Miss Unavailable ### Beta Citation Char Location ### Beta Citation Char Location Param ### Beta Citation Config ### Beta Citation Content Block Location ### Beta Citation Content Block Location Param ### Beta Citation Page Location ### Beta Citation Page Location Param ### Beta Citation Search Result Location ### Beta Citation Search Result Location Param ### Beta Citation Web Search Result Location Param ### Beta Citations Config Param ### Beta Citations Delta ### Beta Citations Web Search Result Location ### Beta Clear Thinking 20251015 Edit ### Beta Clear Thinking 20251015 Edit Response ### Beta Clear Tool Uses 20250919 Edit ### Beta Clear Tool Uses 20250919 Edit Response ### Beta Code Execution Output Block ### Beta Code Execution Output Block Param ### Beta Code Execution Result Block ### Beta Code Execution Result Block Param ### Beta Code Execution Tool 20250522 ### Beta Code Execution Tool 20250825 ### Beta Code Execution Tool 20260120 ### Beta Code Execution Tool 20260521 ### Beta Code Execution Tool Result Block ### Beta Code Execution Tool Result Block Content ### Beta Code Execution Tool Result Block Param ### Beta Code Execution Tool Result Block Param Content ### Beta Code Execution Tool Result Error ### Beta Code Execution Tool Result Error Code ### Beta Code Execution Tool Result Error Param ### Beta Compact 20260112 Edit ### Beta Compaction Block ### Beta Compaction Block Param ### Beta Compaction Content Block Delta ### Beta Compaction Iteration Usage ### Beta Computer Cursor Position Config ### Beta Computer Double Click Config ### Beta Computer Hold Key Config ### Beta Computer Key Config ### Beta Computer Left Click Config ### Beta Computer Left Click Drag Config ### Beta Computer Left Mouse Down Config ### Beta Computer Left Mouse Up Config ### Beta Computer Middle Click Config ### Beta Computer Mouse Move Config ### Beta Computer Right Click Config ### Beta Computer Screenshot Config ### Beta Computer Scroll Config ### Beta Computer Toolset 20260801 ### Beta Computer Toolset Configs ### Beta Computer Triple Click Config ### Beta Computer Type Config ### Beta Computer Wait Config ### Beta Computer Zoom Config ### Beta Container ### Beta Container Params ### Beta Container Upload Block ### Beta Container Upload Block Param ### Beta Content Block ### Beta Content Block Param ### Beta Content Block Source ### Beta Content Block Source Content ### Beta Context Management Config ### Beta Context Management Response ### Beta Count Tokens Context Management Response ### Beta Diagnostics ### Beta Diagnostics Param ### Beta Direct Caller ### Beta Document Block ### Beta Encrypted Code Execution Result Block ### Beta Encrypted Code Execution Result Block Param ### Beta Fallback Block ### Beta Fallback Block Param ### Beta Fallback Credit Not Applied ### Beta Fallback Credit Redeemed ### Beta Fallback Credit Token Param ### Beta Fallback Credit Usage ### Beta Fallback Info ### Beta Fallback Info Param ### Beta Fallback Message Iteration Usage ### Beta Fallback Param ### Beta Fallback Refusal Trigger ### Beta Fallbacks Param ### Beta File Document Source ### Beta File Image Source ### Beta Image Block Param ### Beta Image Transformations Param ### Beta Input JSON Delta ### Beta Input Tokens Clear At Least ### Beta Input Tokens Trigger ### Beta Iterations Usage ### Beta JSON Output Format ### Beta MCP Tool Config ### Beta MCP Tool Default Config ### Beta MCP Tool Result Block ### Beta MCP Tool Use Block ### Beta MCP Tool Use Block Param ### Beta MCP Toolset ### Beta Memory Tool 20250818 ### Beta Memory Tool 20250818 Command ### Beta Memory Tool 20250818 Create Command ### Beta Memory Tool 20250818 Delete Command ### Beta Memory Tool 20250818 Insert Command ### Beta Memory Tool 20250818 Rename Command ### Beta Memory Tool 20250818 Str Replace Command ### Beta Memory Tool 20250818 View Command ### Beta Message ### Beta Message Delta Usage ### Beta Message Iteration Usage ### Beta Message Param ### Beta Message Tokens Count ### Beta Metadata ### Beta Output Config ### Beta Output Tokens Details ### Beta Plain Text Source ### Beta Raw Content Block Delta ### Beta Raw Content Block Delta Event ### Beta Raw Content Block Start Event ### Beta Raw Content Block Stop Event ### Beta Raw Message Delta Event ### Beta Raw Message Start Event ### Beta Raw Message Stop Event ### Beta Raw Message Stream Event ### Beta Redacted Thinking Block ### Beta Redacted Thinking Block Param ### Beta Refusal Stop Details ### Beta Request Document Block ### Beta Request MCP Server Tool Configuration ### Beta Request MCP Server URL Definition ### Beta Request MCP Tool Result Block Param ### Beta Request Tool Addition Block ### Beta Request Tool Removal Block ### Beta Search Result Block Param ### Beta Server Tool Caller ### Beta Server Tool Caller 20260120 ### Beta Server Tool Usage ### Beta Server Tool Use Block ### Beta Server Tool Use Block Param ### Beta Signature Delta ### Beta Skill ### Beta Skill Params ### Beta Stop Reason ### Beta Text Block ### Beta Text Block Param ### Beta Text Citation ### Beta Text Citation Param ### Beta Text Delta ### Beta Text Editor Code Execution Create Result Block ### Beta Text Editor Code Execution Create Result Block Param ### Beta Text Editor Code Execution Str Replace Result Block ### Beta Text Editor Code Execution Str Replace Result Block Param ### Beta Text Editor Code Execution Tool Result Block ### Beta Text Editor Code Execution Tool Result Block Param ### Beta Text Editor Code Execution Tool Result Error ### Beta Text Editor Code Execution Tool Result Error Param ### Beta Text Editor Code Execution View Result Block ### Beta Text Editor Code Execution View Result Block Param ### Beta Thinking Block ### Beta Thinking Block Param ### Beta Thinking Config Adaptive ### Beta Thinking Config Disabled ### Beta Thinking Config Enabled ### Beta Thinking Config Param ### Beta Thinking Delta ### Beta Thinking Turns ### Beta Token Task Budget ### Beta Tool ### Beta Tool Bash 20241022 ### Beta Tool Bash 20250124 ### Beta Tool Change MCP Tool Reference ### Beta Tool Change MCP Toolset Reference ### Beta Tool Change Tool Reference ### Beta Tool Choice ### Beta Tool Choice Any ### Beta Tool Choice Auto ### Beta Tool Choice None ### Beta Tool Choice Tool ### Beta Tool Computer Use 20241022 ### Beta Tool Computer Use 20250124 ### Beta Tool Computer Use 20251124 ### Beta Tool Reference Block ### Beta Tool Reference Block Param ### Beta Tool Result Block Param ### Beta Tool Search Tool Bm25 20251119 ### Beta Tool Search Tool Regex 20251119 ### Beta Tool Search Tool Result Block ### Beta Tool Search Tool Result Block Param ### Beta Tool Search Tool Result Error ### Beta Tool Search Tool Result Error Param ### Beta Tool Search Tool Search Result Block ### Beta Tool Search Tool Search Result Block Param ### Beta Tool Text Editor 20241022 ### Beta Tool Text Editor 20250124 ### Beta Tool Text Editor 20250429 ### Beta Tool Text Editor 20250728 ### Beta Tool Union ### Beta Tool Use Block ### Beta Tool Use Block Param ### Beta Tool Uses Keep ### Beta Tool Uses Trigger ### Beta URL Image Source ### Beta URL PDF Source ### Beta Usage ### Beta User Location ### Beta Web Fetch Block ### Beta Web Fetch Block Param ### Beta Web Fetch Tool 20250910 ### Beta Web Fetch Tool 20260209 ### Beta Web Fetch Tool 20260309 ### Beta Web Fetch Tool 20260318 ### Beta Web Fetch Tool Result Block ### Beta Web Fetch Tool Result Block Param ### Beta Web Fetch Tool Result Error Block ### Beta Web Fetch Tool Result Error Block Param ### Beta Web Fetch Tool Result Error Code ### Beta Web Search Result Block ### Beta Web Search Result Block Param ### Beta Web Search Tool 20250305 ### Beta Web Search Tool 20260209 ### Beta Web Search Tool 20260318 ### Beta Web Search Tool Request Error ### Beta Web Search Tool Result Block ### Beta Web Search Tool Result Block Content ### Beta Web Search Tool Result Block Param ### Beta Web Search Tool Result Block Param Content ### Beta Web Search Tool Result Error ### Beta Web Search Tool Result Error Code # Batches ## Create a Message Batch ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Retrieve a Message Batch ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## List Message Batches ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Cancel a Message Batch ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Delete a Message Batch ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Retrieve Message Batch results ### Path Parameters ### Header Parameters ### Returns ### Example ## Domain Types ### Beta Deleted Message Batch ### Beta Message Batch ### Beta Message Batch Canceled Result ### Beta Message Batch Errored Result ### Beta Message Batch Expired Result ### Beta Message Batch Individual Response ### Beta Message Batch Request Counts ### Beta Message Batch Result ### Beta Message Batch Succeeded Result # Agents ## Create Agent ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## List Agents ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Get Agent ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Update Agent ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Archive Agent ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Managed Agents Advisor ### Beta Managed Agents Agent ### Beta Managed Agents Agent Reference ### Beta Managed Agents Agent Tool Config ### Beta Managed Agents Agent Tool Config Params ### Beta Managed Agents Agent Toolset Default Config ### Beta Managed Agents Agent Toolset Default Config Params ### Beta Managed Agents Agent Toolset20260401 ### Beta Managed Agents Agent Toolset20260401 Bash Input ### Beta Managed Agents Agent Toolset20260401 Edit Input ### Beta Managed Agents Agent Toolset20260401 Glob Input ### Beta Managed Agents Agent Toolset20260401 Grep Input ### Beta Managed Agents Agent Toolset20260401 Params ### Beta Managed Agents Agent Toolset20260401 Read Input ### Beta Managed Agents Agent Toolset20260401 Write Input ### Beta Managed Agents Always Allow Policy ### Beta Managed Agents Always Ask Policy ### Beta Managed Agents Anthropic Skill ### Beta Managed Agents Anthropic Skill Params ### Beta Managed Agents Bash Tool Config ### Beta Managed Agents Bash Tool Config Params ### Beta Managed Agents Custom Skill ### Beta Managed Agents Custom Skill Params ### Beta Managed Agents Custom Tool ### Beta Managed Agents Custom Tool Input Schema ### Beta Managed Agents Custom Tool Params ### Beta Managed Agents Edit Tool Config ### Beta Managed Agents Edit Tool Config Params ### Beta Managed Agents Effort High ### Beta Managed Agents Effort Low ### Beta Managed Agents Effort Max ### Beta Managed Agents Effort Medium ### Beta Managed Agents Effort Xhigh ### Beta Managed Agents Glob Tool Config ### Beta Managed Agents Glob Tool Config Params ### Beta Managed Agents Grep Tool Config ### Beta Managed Agents Grep Tool Config Params ### Beta Managed Agents MCP Server URL Definition ### Beta Managed Agents MCP Tool Config ### Beta Managed Agents MCP Tool Config Params ### Beta Managed Agents MCP Toolset ### Beta Managed Agents MCP Toolset Default Config ### Beta Managed Agents MCP Toolset Default Config Params ### Beta Managed Agents MCP Toolset Params ### Beta Managed Agents Model ### Beta Managed Agents Model Config ### Beta Managed Agents Model Config Params ### Beta Managed Agents Multiagent Coordinator ### Beta Managed Agents Multiagent Coordinator Params ### Beta Managed Agents Multiagent Self Params ### Beta Managed Agents Read Tool Config ### Beta Managed Agents Read Tool Config Params ### Beta Managed Agents Session Thread Agent ### Beta Managed Agents Skill Params ### Beta Managed Agents URL MCP Server Params ### Beta Managed Agents User Location ### Beta Managed Agents Web Fetch Tool Config ### Beta Managed Agents Web Fetch Tool Config Params ### Beta Managed Agents Web Search Tool Config ### Beta Managed Agents Web Search Tool Config Params ### Beta Managed Agents Write Tool Config ### Beta Managed Agents Write Tool Config Params # Versions ## List Agent Versions ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response # Environments ## Create Environment ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## List Environments ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Get Environment ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Update Environment ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Delete Environment ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Archive Environment ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Cloud Config ### Beta Cloud Config Params ### Beta Environment ### Beta Environment Delete Response ### Beta Limited Network ### Beta Limited Network Params ### Beta Packages ### Beta Packages Params ### Beta Self Hosted Config ### Beta Self Hosted Config Params ### Beta Unrestricted Network # Work ## Get Work Item ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Poll for Work ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Acknowledge Work ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Record Heartbeat ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Stop Work ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## List Work Items ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Update Work Item ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Get Queue Statistics ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Self Hosted Work ### Beta Self Hosted Work Heartbeat Response ### Beta Self Hosted Work List Response ### Beta Self Hosted Work Queue Stats ### Beta Self Hosted Work Stop Request ### Beta Self Hosted Work Update Request ### Beta Session Work Data # Sessions ## Create Session ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## List Sessions ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Get Session ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Update Session ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Delete Session ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Archive Session ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Managed Agents Advisor Params ### Beta Managed Agents Agent Message Preview ### Beta Managed Agents Agent Params ### Beta Managed Agents Agent Thinking Preview ### Beta Managed Agents Agent With Overrides Params ### Beta Managed Agents Branch Checkout ### Beta Managed Agents Budget Limit ### Beta Managed Agents Cache Creation Usage ### Beta Managed Agents Commit Checkout ### Beta Managed Agents Deleted Session ### Beta Managed Agents Delta Content ### Beta Managed Agents Delta Event ### Beta Managed Agents Delta Type ### Beta Managed Agents File Resource Params ### Beta Managed Agents GitHub Repository Resource Params ### Beta Managed Agents Memory Store Resource Param ### Beta Managed Agents Multiagent ### Beta Managed Agents Multiagent Params ### Beta Managed Agents Multiagent Roster Entry Params ### Beta Managed Agents Outcome Evaluation Resource ### Beta Managed Agents Server Tool Usage ### Beta Managed Agents Session ### Beta Managed Agents Session Agent ### Beta Managed Agents Session Agent Update ### Beta Managed Agents Session Multiagent Coordinator ### Beta Managed Agents Session Stats ### Beta Managed Agents Session Updated Event ### Beta Managed Agents Session Usage ### Beta Managed Agents Session Usage Event ### Beta Managed Agents Start Event ### Beta Managed Agents Start Event Preview ### Beta Managed Agents System Content Block ### Beta Managed Agents System Message Event ### Beta Managed Agents User Tool Result Event # Events ## List Events ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Send Events ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Stream Events ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Managed Agents Agent Custom Tool Use Event ### Beta Managed Agents Agent MCP Tool Result Event ### Beta Managed Agents Agent MCP Tool Use Event ### Beta Managed Agents Agent Message Event ### Beta Managed Agents Agent Thinking Event ### Beta Managed Agents Agent Thread Context Compacted Event ### Beta Managed Agents Agent Thread Message Received Event ### Beta Managed Agents Agent Thread Message Sent Event ### Beta Managed Agents Agent Tool Result Event ### Beta Managed Agents Agent Tool Use Event ### Beta Managed Agents Base64 Document Source ### Beta Managed Agents Base64 Image Source ### Beta Managed Agents Billing Error ### Beta Managed Agents Credential Host Unreachable Error ### Beta Managed Agents Document Block ### Beta Managed Agents Event Params ### Beta Managed Agents File Document Source ### Beta Managed Agents File Image Source ### Beta Managed Agents File Rubric ### Beta Managed Agents File Rubric Params ### Beta Managed Agents Image Block ### Beta Managed Agents MCP Authentication Failed Error ### Beta Managed Agents MCP Connection Failed Error ### Beta Managed Agents Model Overloaded Error ### Beta Managed Agents Model Rate Limited Error ### Beta Managed Agents Model Request Failed Error ### Beta Managed Agents Plain Text Document Source ### Beta Managed Agents Redacted Block ### Beta Managed Agents Retry Status Exhausted ### Beta Managed Agents Retry Status Retrying ### Beta Managed Agents Retry Status Terminal ### Beta Managed Agents Search Result Block ### Beta Managed Agents Search Result Citations ### Beta Managed Agents Search Result Content ### Beta Managed Agents Send Session Events ### Beta Managed Agents Session Budget Reached ### Beta Managed Agents Session Deleted Event ### Beta Managed Agents Session End Turn ### Beta Managed Agents Session Error Event ### Beta Managed Agents Session Event ### Beta Managed Agents Session Requires Action ### Beta Managed Agents Session Retries Exhausted ### Beta Managed Agents Session Status Idle Event ### Beta Managed Agents Session Status Rescheduled Event ### Beta Managed Agents Session Status Running Event ### Beta Managed Agents Session Status Terminated Event ### Beta Managed Agents Session Thread Created Event ### Beta Managed Agents Session Thread Status Idle Event ### Beta Managed Agents Session Thread Status Rescheduled Event ### Beta Managed Agents Session Thread Status Running Event ### Beta Managed Agents Session Thread Status Terminated Event ### Beta Managed Agents Session Usage Snapshot ### Beta Managed Agents Span Model Request End Event ### Beta Managed Agents Span Model Request Start Event ### Beta Managed Agents Span Model Usage ### Beta Managed Agents Span Outcome Evaluation End Event ### Beta Managed Agents Span Outcome Evaluation Ongoing Event ### Beta Managed Agents Span Outcome Evaluation Start Event ### Beta Managed Agents Stream Session Events ### Beta Managed Agents System Message Event Params ### Beta Managed Agents Text Block ### Beta Managed Agents Text Rubric ### Beta Managed Agents Text Rubric Params ### Beta Managed Agents Unknown Error ### Beta Managed Agents URL Document Source ### Beta Managed Agents URL Image Source ### Beta Managed Agents User Custom Tool Result Event ### Beta Managed Agents User Custom Tool Result Event Params ### Beta Managed Agents User Define Outcome Event ### Beta Managed Agents User Define Outcome Event Params ### Beta Managed Agents User Interrupt Event ### Beta Managed Agents User Interrupt Event Params ### Beta Managed Agents User Message Event ### Beta Managed Agents User Message Event Params ### Beta Managed Agents User Tool Confirmation Event ### Beta Managed Agents User Tool Confirmation Event Params ### Beta Managed Agents User Tool Result Event Params # Resources ## Add Session Resource ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## List Session Resources ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Get Session Resource ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Update Session Resource ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Delete Session Resource ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Managed Agents Delete Session Resource ### Beta Managed Agents File Resource ### Beta Managed Agents GitHub Repository Resource ### Beta Managed Agents Memory Store Resource ### Beta Managed Agents Session Resource ### Resource Retrieve Response ### Resource Update Response # Threads ## List Session Threads ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Get Session Thread ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Archive Session Thread ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Managed Agents Session Thread ### Beta Managed Agents Session Thread Stats ### Beta Managed Agents Session Thread Status ### Beta Managed Agents Session Thread Usage ### Beta Managed Agents Stream Session Thread Events # Events ## List Session Thread Events ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Stream Session Thread Events ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response # Deployments ## Create Deployment ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## List Deployments ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Get Deployment ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Update Deployment ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Archive Deployment ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Run Deployment Now ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Pause Deployment ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Unpause Deployment ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Managed Agents Agent Archived Deployment Paused Reason Error ### Beta Managed Agents Cron Schedule ### Beta Managed Agents Cron Schedule Params ### Beta Managed Agents Deployment ### Beta Managed Agents Deployment Initial Event ### Beta Managed Agents Deployment Initial Event Params ### Beta Managed Agents Deployment Paused Reason ### Beta Managed Agents Deployment Paused Reason Error ### Beta Managed Agents Deployment Status ### Beta Managed Agents Deployment System Message Event ### Beta Managed Agents Deployment User Define Outcome Event ### Beta Managed Agents Deployment User Message Event ### Beta Managed Agents Environment Archived Deployment Paused Reason Error ### Beta Managed Agents Environment Not Found Deployment Paused Reason Error ### Beta Managed Agents Error Deployment Paused Reason ### Beta Managed Agents File Not Found Deployment Paused Reason Error ### Beta Managed Agents File Resource Config ### Beta Managed Agents GitHub Repository Resource Config ### Beta Managed Agents Manual Deployment Paused Reason ### Beta Managed Agents MCP Egress Blocked Deployment Paused Reason Error ### Beta Managed Agents Memory Store Archived Deployment Paused Reason Error ### Beta Managed Agents Memory Store Resource Config ### Beta Managed Agents Organization Disabled Deployment Paused Reason Error ### Beta Managed Agents Schedule ### Beta Managed Agents Schedule Params ### Beta Managed Agents Self Hosted Resources Unsupported Deployment Paused Reason Error ### Beta Managed Agents Session Resource Config ### Beta Managed Agents Session Resource Not Found Deployment Paused Reason Error ### Beta Managed Agents Skill Not Found Deployment Paused Reason Error ### Beta Managed Agents Unknown Deployment Paused Reason Error ### Beta Managed Agents Vault Archived Deployment Paused Reason Error ### Beta Managed Agents Vault Not Found Deployment Paused Reason Error ### Beta Managed Agents Workspace Archived Deployment Paused Reason Error # Deployment Runs ## List Deployment Runs ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Get Deployment Run ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Managed Agents Agent Archived Run Error ### Beta Managed Agents Deployment Run ### Beta Managed Agents Environment Archived Run Error ### Beta Managed Agents Environment Not Found Run Error ### Beta Managed Agents File Not Found Run Error ### Beta Managed Agents Manual Trigger Context ### Beta Managed Agents MCP Egress Blocked Run Error ### Beta Managed Agents Memory Store Archived Run Error ### Beta Managed Agents Organization Disabled Run Error ### Beta Managed Agents Schedule Trigger Context ### Beta Managed Agents Self Hosted Resources Unsupported Run Error ### Beta Managed Agents Session Creation Rejected Run Error ### Beta Managed Agents Session Rate Limited Run Error ### Beta Managed Agents Session Resource Not Found Run Error ### Beta Managed Agents Skill Not Found Run Error ### Beta Managed Agents Trigger Context ### Beta Managed Agents Trigger Type ### Beta Managed Agents Unknown Run Error ### Beta Managed Agents Vault Archived Run Error ### Beta Managed Agents Vault Not Found Run Error ### Beta Managed Agents Workspace Archived Run Error # Vaults ## Create Vault ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## List Vaults ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Get Vault ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Update Vault ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Delete Vault ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Archive Vault ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Managed Agents Deleted Vault ### Beta Managed Agents Vault # Credentials ## Create Credential ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## List Credentials ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Get Credential ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Update Credential ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Delete Credential ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Archive Credential ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Validate Credential ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Managed Agents Credential ### Beta Managed Agents Credential Networking Params ### Beta Managed Agents Credential Validation ### Beta Managed Agents Credential Validation Status ### Beta Managed Agents Deleted Credential ### Beta Managed Agents Environment Variable Auth Response ### Beta Managed Agents Environment Variable Create Params ### Beta Managed Agents Environment Variable Update Params ### Beta Managed Agents Injection Location Params ### Beta Managed Agents Injection Location Response ### Beta Managed Agents Injection Location Update Params ### Beta Managed Agents Limited Credential Networking Params ### Beta Managed Agents Limited Credential Networking Response ### Beta Managed Agents MCP OAuth Auth Response ### Beta Managed Agents MCP OAuth Create Params ### Beta Managed Agents MCP OAuth Refresh Params ### Beta Managed Agents MCP OAuth Refresh Response ### Beta Managed Agents MCP OAuth Refresh Update Params ### Beta Managed Agents MCP OAuth Update Params ### Beta Managed Agents MCP Probe ### Beta Managed Agents Refresh HTTP Response ### Beta Managed Agents Refresh Object ### Beta Managed Agents Static Bearer Auth Response ### Beta Managed Agents Static Bearer Create Params ### Beta Managed Agents Static Bearer Update Params ### Beta Managed Agents Token Endpoint Auth Basic Param ### Beta Managed Agents Token Endpoint Auth Basic Response ### Beta Managed Agents Token Endpoint Auth Basic Update Param ### Beta Managed Agents Token Endpoint Auth None Param ### Beta Managed Agents Token Endpoint Auth None Response ### Beta Managed Agents Token Endpoint Auth Post Param ### Beta Managed Agents Token Endpoint Auth Post Response ### Beta Managed Agents Token Endpoint Auth Post Update Param ### Beta Managed Agents Unrestricted Credential Networking Params ### Beta Managed Agents Unrestricted Credential Networking Response # Memory Stores ## Create a memory store ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## List memory stores ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Retrieve a memory store ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Update a memory store ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Delete a memory store ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Archive a memory store ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Managed Agents Deleted Memory Store ### Beta Managed Agents Memory Store # Memories ## Create a memory ### Path Parameters ### Query Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## List memories ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Retrieve a memory ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Update a memory ### Path Parameters ### Query Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Delete a memory ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Managed Agents Conflict Error ### Beta Managed Agents Content Sha256 Precondition ### Beta Managed Agents Deleted Memory ### Beta Managed Agents Error ### Beta Managed Agents Memory ### Beta Managed Agents Memory List Item ### Beta Managed Agents Memory Path Conflict Error ### Beta Managed Agents Memory Precondition Failed Error ### Beta Managed Agents Memory Prefix ### Beta Managed Agents Memory View ### Beta Managed Agents Precondition # Memory Versions ## List memory versions ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Retrieve a memory version ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Redact a memory version ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Managed Agents Actor ### Beta Managed Agents API Actor ### Beta Managed Agents Memory Version ### Beta Managed Agents Memory Version Operation ### Beta Managed Agents Service Account Actor ### Beta Managed Agents Session Actor ### Beta Managed Agents User Actor # Files ## Upload File ### Header Parameters ### Returns ### Example #### Response ## List Files ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Download File ### Path Parameters ### Header Parameters ### Example ## Get File Metadata ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Delete File ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Deleted File ### Beta File Metadata ### Beta File Scope # Skills ## Create Skill ### Header Parameters ### Returns ### Example #### Response ## List Skills ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Get Skill ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Delete Skill ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Skill Create Response ### Skill List Response ### Skill Retrieve Response ### Skill Delete Response # Versions ## Create Skill Version ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## List Skill Versions ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Download Skill Version Content ### Path Parameters ### Header Parameters ### Example ## Get Skill Version ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Delete Skill Version ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Version Create Response ### Version List Response ### Version Retrieve Response ### Version Delete Response # User Profiles ## Create User Profile ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## List User Profiles ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Get User Profile ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Update User Profile ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Create Enrollment URL ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Beta User Profile ### Beta User Profile Enrollment URL ### Beta User Profile Trust Grant # Dreams ## Create a Dream ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## List Dreams ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Get a Dream ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Cancel a Dream ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Archive a Dream ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Dream ### Beta Dream Error ### Beta Dream Input ### Beta Dream Memory Store Input ### Beta Dream Memory Store Output ### Beta Dream Model Config ### Beta Dream Model Config Param ### Beta Dream Output ### Beta Dream Sessions Input ### Beta Dream Status ### Beta Dream Usage ### Beta Output Behavior ### Beta Output Behavior Create New ### Beta Output Behavior Update Existing # Tunnels ## Create Tunnel ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Get Tunnel ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## List Tunnels ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Archive Tunnel ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Reveal Tunnel Token ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Rotate Tunnel Token ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Tunnel ### Beta Tunnel Token # Certificates ## Create Tunnel Certificate ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Get Tunnel Certificate ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## List Tunnel Certificates ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Archive Tunnel Certificate ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Tunnel Certificate # Webhooks ## Domain Types ### Beta Webhook Agent Archived Event Data ### Beta Webhook Agent Created Event Data ### Beta Webhook Agent Deleted Event Data ### Beta Webhook Agent Updated Event Data ### Beta Webhook Deployment Archived Event Data ### Beta Webhook Deployment Created Event Data ### Beta Webhook Deployment Deleted Event Data ### Beta Webhook Deployment Paused Event Data ### Beta Webhook Deployment Run Failed Event Data ### Beta Webhook Deployment Run Started Event Data ### Beta Webhook Deployment Run Succeeded Event Data ### Beta Webhook Deployment Unpaused Event Data ### Beta Webhook Deployment Updated Event Data ### Beta Webhook Environment Archived Event Data ### Beta Webhook Environment Created Event Data ### Beta Webhook Environment Deleted Event Data ### Beta Webhook Environment Updated Event Data ### Beta Webhook Event ### Beta Webhook Event Data ### Beta Webhook Memory Store Archived Event Data ### Beta Webhook Memory Store Created Event Data ### Beta Webhook Memory Store Deleted Event Data ### Beta Webhook Session Archived Event Data ### Beta Webhook Session Budget Reached Event Data ### Beta Webhook Session Created Event Data ### Beta Webhook Session Deleted Event Data ### Beta Webhook Session Idled Event Data ### Beta Webhook Session Outcome Evaluation Ended Event Data ### Beta Webhook Session Pending Event Data ### Beta Webhook Session Requires Action Event Data ### Beta Webhook Session Running Event Data ### Beta Webhook Session Status Idled Event Data ### Beta Webhook Session Status Rescheduled Event Data ### Beta Webhook Session Status Run Started Event Data ### Beta Webhook Session Status Terminated Event Data ### Beta Webhook Session Thread Created Event Data ### Beta Webhook Session Thread Idled Event Data ### Beta Webhook Session Thread Terminated Event Data ### Beta Webhook Session Updated Event Data ### Beta Webhook Vault Archived Event Data ### Beta Webhook Vault Created Event Data ### Beta Webhook Vault Credential Archived Event Data ### Beta Webhook Vault Credential Created Event Data ### Beta Webhook Vault Credential Deleted Event Data ### Beta Webhook Vault Credential Refresh Failed Event Data ### Beta Webhook Vault Deleted Event Data ### Unwrap Webhook Event
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 · +1020 / -1799 lines
### Headers ### Body parameters #### Response (200) ### Query parameters ### Headers #### Response (200) ### Path parameters ### Query parameters ### Headers #### Response (200) ### Path parameters ### Headers ### Body parameters #### Response (200) ### Path parameters ### Headers #### Response (200) ## Domain types ## Agents › Versions ### List Agent Versions #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Header Parameters ### Body Parameters #### Response ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters ### Body Parameters #### Response ### Path Parameters ### Header Parameters #### Response ## Domain Types # Versions ## List Agent Versions ### Path Parameters ### Query Parameters ### Header Parameters #### Response
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 1
1---
2title: Agents
3url: https://platform.claude.com/docs/en/api/beta/agents
4---
5
61# Agents
72
83## Create Agent
94
10**post** `/v1/agents`
5**POST** `/v1/agents`
116
127Create Agent
138
14### Header Parameters
9### Headers
1510
1611- `"anthropic-beta": optional array of AnthropicBeta`
1712
from line 84
8984
9085 - `"mid-conversation-tool-changes-2026-07-01"`
9186
92### Body Parameters
87### Body parameters
9388
9489- `model: BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams`
9590
from line 156
161156
162157 - `string`
163158
164 - `BetaManagedAgentsModelConfigParams object { id, effort, inference_geo, speed }`
159 - `BetaManagedAgentsModelConfigParams object`
165160
166161 An object that defines additional configuration control over model use
167162
from line 184
189184
190185 - `"max"`
191186
192 - `BetaManagedAgentsEffortLow object { type }`
187 - `BetaManagedAgentsEffortLow object`
193188
194189 Low effort. Favors latency over reasoning depth.
195190
196191 - `type: "low"`
197192
198 - `"low"`
199
200 - `BetaManagedAgentsEffortMedium object { type }`
193 - `BetaManagedAgentsEffortMedium object`
201194
202195 Medium effort. Balances latency and reasoning depth.
203196
204197 - `type: "medium"`
205198
206 - `"medium"`
207
208 - `BetaManagedAgentsEffortHigh object { type }`
199 - `BetaManagedAgentsEffortHigh object`
209200
210201 High effort. Favors reasoning depth.
211202
212203 - `type: "high"`
213204
214 - `"high"`
215
216 - `BetaManagedAgentsEffortXhigh object { type }`
205 - `BetaManagedAgentsEffortXhigh object`
217206
218207 Extra-high effort. Not all models accept this level.
219208
220209 - `type: "xhigh"`
221210
222 - `"xhigh"`
223
224 - `BetaManagedAgentsEffortMax object { type }`
211 - `BetaManagedAgentsEffortMax object`
225212
226213 Maximum effort. Favors reasoning depth over latency.
227214
228215 - `type: "max"`
229216
230 - `"max"`
231
232217 - `inference_geo: optional string or null`
233218
234219 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. On update, `model` is whole-object replacement — omitting inference_geo clears it.
from line 230
245230
246231 Human-readable name for the agent.
247232
233 minLength: 1, maxLength: 256
234
248235- `description: optional string or null`
249236
250237 Description of what the agent does.
251238
239 maxLength: 2048
240
252241- `mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams`
253242
254243 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).
from line 246
257246
258247 Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.
259248
249 minLength: 1, maxLength: 255
250
260251 - `type: "url"`
261252
262 - `"url"`
263
264253 - `url: string`
265254
266255 Endpoint URL for the MCP server.
267256
257 maxLength: 2048
258
268259- `metadata: optional map[string]`
269260
270261 Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.
from line 270
279270
280271 - `string`
281272
282 - `BetaManagedAgentsAgentParams object { id, type, version }`
273 - `BetaManagedAgentsAgentParams object`
283274
284275 Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version
285276
from line 278
287278
288279 The `agent` ID.
289280
281 minLength: 1, maxLength: 128
282
290283 - `type: "agent"`
291284
292 - `"agent"`
293
294285 - `version: optional number`
295286
296287 The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.
297288
298 - `BetaManagedAgentsMultiagentSelfParams object { type }`
289 format: int32
290
291 - `BetaManagedAgentsMultiagentSelfParams object`
299292
300293 Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference.
301294
302295 - `type: "self"`
303296
304 - `"self"`
305
306 - `BetaManagedAgentsAdvisorParams object { model, type }`
297 - `BetaManagedAgentsAdvisorParams object`
307298
308299 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`.
309300
from line 302
311302
312303 A Claude model id. The model must be permitted as an advisor for this agent's model — see the sessions/threads/advisor spec.
313304
305 minLength: 1, maxLength: 256
306
314307 - `type: "advisor"`
315308
316 - `"advisor"`
317
318309 - `type: "coordinator"`
319310
320 - `"coordinator"`
321
322311- `skills: optional array of BetaManagedAgentsSkillParams`
323312
324313 Skills available to the agent.
325314
326 - `BetaManagedAgentsAnthropicSkillParams object { skill_id, type, version }`
315 - `BetaManagedAgentsAnthropicSkillParams object`
327316
328317 An Anthropic-managed skill.
329318
from line 320
331320
332321 Identifier of the Anthropic skill (e.g., "xlsx").
333322
323 minLength: 1, maxLength: 64
324
334325 - `type: "anthropic"`
335326
336 - `"anthropic"`
337
338327 - `version: optional string or null`
339328
340329 Version to pin. Defaults to latest if omitted.
341330
342 - `BetaManagedAgentsCustomSkillParams object { skill_id, type, version }`
331 minLength: 1, maxLength: 64
332
333 - `BetaManagedAgentsCustomSkillParams object`
343334
344335 A user-created custom skill.
345336
from line 338
347338
348339 Tagged ID of the custom skill (e.g., "skill_01XJ5...").
349340
341 minLength: 1, maxLength: 64
342
350343 - `type: "custom"`
351344
352 - `"custom"`
353
354345 - `version: optional string or null`
355346
356347 Version to pin. Defaults to latest if omitted.
357348
349 minLength: 1, maxLength: 64
350
358351- `system: optional string or null`
359352
360353 System prompt for the agent.
361354
355 maxLength: 100000
356
362357- `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams`
363358
364359 Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed.
365360
366 - `BetaManagedAgentsAgentToolset20260401Params object { type, configs, default_config }`
361 - `BetaManagedAgentsAgentToolset20260401Params object`
367362
368363 Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.
369364
370365 - `type: "agent_toolset_20260401"`
371366
372 - `"agent_toolset_20260401"`
373
374367 - `configs: optional array of BetaManagedAgentsAgentToolConfigParams`
375368
376369 Per-tool configuration overrides.
377370
378 - `BetaManagedAgentsBashToolConfigParams object { name, enabled, permission_policy, type }`
371 - `BetaManagedAgentsBashToolConfigParams object`
379372
380373 Configuration override for the bash tool.
381374
from line 376
383376
384377 Must be "bash".
385378
386 - `"bash"`
387
388379 - `enabled: optional boolean or null`
389380
390381 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 384
393384
394385 Permission policy for tool execution.
395386
396 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
387 - `BetaManagedAgentsAlwaysAllowPolicy object`
397388
398389 Tool calls are automatically approved without user confirmation.
399390
400391 - `type: "always_allow"`
401392
402 - `"always_allow"`
403
404 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
393 - `BetaManagedAgentsAlwaysAskPolicy object`
405394
406395 Tool calls require user confirmation before execution.
407396
408397 - `type: "always_ask"`
409398
410 - `"always_ask"`
411
412399 - `type: optional "bash"`
413400
414 - `"bash"`
415
416 - `BetaManagedAgentsEditToolConfigParams object { name, enabled, permission_policy, type }`
401 - `BetaManagedAgentsEditToolConfigParams object`
417402
418403 Configuration override for the edit tool.
419404
from line 406
421406
422407 Must be "edit".
423408
424 - `"edit"`
425
426409 - `enabled: optional boolean or null`
427410
428411 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 414
431414
432415 Permission policy for tool execution.
433416
434 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
417 - `BetaManagedAgentsAlwaysAllowPolicy object`
435418
436419 Tool calls are automatically approved without user confirmation.
437420
438 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
421 - `BetaManagedAgentsAlwaysAskPolicy object`
439422
440423 Tool calls require user confirmation before execution.
441424
442425 - `type: optional "edit"`
443426
444 - `"edit"`
445
446 - `BetaManagedAgentsReadToolConfigParams object { name, enabled, permission_policy, type }`
427 - `BetaManagedAgentsReadToolConfigParams object`
447428
448429 Configuration override for the read tool.
449430
from line 432
451432
452433 Must be "read".
453434
454 - `"read"`
455
456435 - `enabled: optional boolean or null`
457436
458437 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 440
461440
462441 Permission policy for tool execution.
463442
464 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
443 - `BetaManagedAgentsAlwaysAllowPolicy object`
465444
466445 Tool calls are automatically approved without user confirmation.
467446
468 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
447 - `BetaManagedAgentsAlwaysAskPolicy object`
469448
470449 Tool calls require user confirmation before execution.
471450
472451 - `type: optional "read"`
473452
474 - `"read"`
475
476 - `BetaManagedAgentsWriteToolConfigParams object { name, enabled, permission_policy, type }`
453 - `BetaManagedAgentsWriteToolConfigParams object`
477454
478455 Configuration override for the write tool.
479456
from line 458
481458
482459 Must be "write".
483460
484 - `"write"`
485
486461 - `enabled: optional boolean or null`
487462
488463 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 466
491466
492467 Permission policy for tool execution.
493468
494 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
469 - `BetaManagedAgentsAlwaysAllowPolicy object`
495470
496471 Tool calls are automatically approved without user confirmation.
497472
498 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
473 - `BetaManagedAgentsAlwaysAskPolicy object`
499474
500475 Tool calls require user confirmation before execution.
501476
502477 - `type: optional "write"`
503478
504 - `"write"`
505
506 - `BetaManagedAgentsGlobToolConfigParams object { name, enabled, permission_policy, type }`
479 - `BetaManagedAgentsGlobToolConfigParams object`
507480
508481 Configuration override for the glob tool.
509482
from line 484
511484
512485 Must be "glob".
513486
514 - `"glob"`
515
516487 - `enabled: optional boolean or null`
517488
518489 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 492
521492
522493 Permission policy for tool execution.
523494
524 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
495 - `BetaManagedAgentsAlwaysAllowPolicy object`
525496
526497 Tool calls are automatically approved without user confirmation.
527498
528 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
499 - `BetaManagedAgentsAlwaysAskPolicy object`
529500
530501 Tool calls require user confirmation before execution.
531502
532503 - `type: optional "glob"`
533504
534 - `"glob"`
535
536 - `BetaManagedAgentsGrepToolConfigParams object { name, enabled, permission_policy, type }`
505 - `BetaManagedAgentsGrepToolConfigParams object`
537506
538507 Configuration override for the grep tool.
539508
from line 510
541510
542511 Must be "grep".
543512
544 - `"grep"`
545
546513 - `enabled: optional boolean or null`
547514
548515 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 518
551518
552519 Permission policy for tool execution.
553520
554 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
521 - `BetaManagedAgentsAlwaysAllowPolicy object`
555522
556523 Tool calls are automatically approved without user confirmation.
557524
558 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
525 - `BetaManagedAgentsAlwaysAskPolicy object`
559526
560527 Tool calls require user confirmation before execution.
561528
562529 - `type: optional "grep"`
563530
564 - `"grep"`
565
566 - `BetaManagedAgentsWebFetchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }`
531 - `BetaManagedAgentsWebFetchToolConfigParams object`
567532
568533 Configuration override for the web_fetch tool.
569534
from line 536
571536
572537 Must be "web_fetch".
573538
574 - `"web_fetch"`
575
576539 - `allowed_domains: optional array of string`
577540
578541 Only fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
from line 552
589552
590553 Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs.
591554
555 format: int32
556
592557 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
593558
594559 Permission policy for tool execution.
595560
596 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
561 - `BetaManagedAgentsAlwaysAllowPolicy object`
597562
598563 Tool calls are automatically approved without user confirmation.
599564
600 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
565 - `BetaManagedAgentsAlwaysAskPolicy object`
601566
602567 Tool calls require user confirmation before execution.
603568
604569 - `type: optional "web_fetch"`
605570
606 - `"web_fetch"`
607
608 - `BetaManagedAgentsWebSearchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }`
571 - `BetaManagedAgentsWebSearchToolConfigParams object`
609572
610573 Configuration override for the web_search tool.
611574
from line 576
613576
614577 Must be "web_search".
615578
616 - `"web_search"`
617
618579 - `allowed_domains: optional array of string`
619580
620581 Only return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
from line 592
631592
632593 Permission policy for tool execution.
633594
634 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
595 - `BetaManagedAgentsAlwaysAllowPolicy object`
635596
636597 Tool calls are automatically approved without user confirmation.
637598
638 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
599 - `BetaManagedAgentsAlwaysAskPolicy object`
639600
640601 Tool calls require user confirmation before execution.
641602
642603 - `type: optional "web_search"`
643604
644 - `"web_search"`
645
646605 - `user_location: optional BetaManagedAgentsUserLocation or null`
647606
648607 Approximate user location for search result localization.
from line 610
651610
652611 Location precision. Only "approximate" is supported.
653612
654 - `"approximate"`
655
656613 - `city: optional string or null`
657614
658615 City name.
659616
617 minLength: 1, maxLength: 255
618
660619 - `country: optional string or null`
661620
662621 Two-letter ISO 3166-1 country code, uppercase.
from line 624
665624
666625 Region or state name.
667626
627 minLength: 1, maxLength: 255
628
668629 - `timezone: optional string or null`
669630
670631 IANA timezone identifier, e.g. "America/Los_Angeles".
671632
633 minLength: 1, maxLength: 255
634
672635 - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or null`
673636
674637 Default configuration for all tools in a toolset.
from line 644
681644
682645 Permission policy for tool execution.
683646
684 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
647 - `BetaManagedAgentsAlwaysAllowPolicy object`
685648
686649 Tool calls are automatically approved without user confirmation.
687650
688 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
651 - `BetaManagedAgentsAlwaysAskPolicy object`
689652
690653 Tool calls require user confirmation before execution.
691654
692 - `BetaManagedAgentsMCPToolsetParams object { mcp_server_name, type, configs, default_config }`
655 - `BetaManagedAgentsMCPToolsetParams object`
693656
694657 Configuration for tools from an MCP server defined in `mcp_servers`.
695658
from line 660
697660
698661 Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.
699662
663 minLength: 1, maxLength: 255
664
700665 - `type: "mcp_toolset"`
701666
702 - `"mcp_toolset"`
703
704667 - `configs: optional array of BetaManagedAgentsMCPToolConfigParams`
705668
706669 Per-tool configuration overrides.
from line 672
709672
710673 Name of the MCP tool to configure. 1-128 characters.
711674
675 minLength: 1, maxLength: 128
676
712677 - `enabled: optional boolean or null`
713678
714679 Whether this tool is enabled. Overrides the `default_config` setting.
from line 682
717682
718683 Permission policy for tool execution.
719684
720 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
685 - `BetaManagedAgentsAlwaysAllowPolicy object`
721686
722687 Tool calls are automatically approved without user confirmation.
723688
724 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
689 - `BetaManagedAgentsAlwaysAskPolicy object`
725690
726691 Tool calls require user confirmation before execution.
727692
from line 702
737702
738703 Permission policy for tool execution.
739704
740 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
705 - `BetaManagedAgentsAlwaysAllowPolicy object`
741706
742707 Tool calls are automatically approved without user confirmation.
743708
744 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
709 - `BetaManagedAgentsAlwaysAskPolicy object`
745710
746711 Tool calls require user confirmation before execution.
747712
748 - `BetaManagedAgentsCustomToolParams object { description, input_schema, name, type }`
713 - `BetaManagedAgentsCustomToolParams object`
749714
750715 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.
751716
from line 718
753718
754719 Description of what the tool does, shown to the agent to help it decide when to use the tool.
755720
721 minLength: 1
722
756723 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
757724
758725 JSON Schema for custom tool input parameters.
759726
760727 - `type: "object"`
761728
762 - `"object"`
763
764729 - `properties: optional map[unknown] or null`
765730
766731 - `required: optional array of string or null`
from line 734
769734
770735 Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.
771736
737 minLength: 1, maxLength: 128
738
772739 - `type: "custom"`
773740
774 - `"custom"`
775
776741### Returns
777742
778- `BetaManagedAgentsAgent object { id, archived_at, created_at, 12 more }`
743- `BetaManagedAgentsAgent object`
779744
780745 A Managed Agents `agent`.
781746
from line 750
785750
786751 A timestamp in RFC 3339 format
787752
753 format: date-time
754
788755 - `created_at: string`
789756
790757 A timestamp in RFC 3339 format
791758
759 format: date-time
760
792761 - `description: string or null`
793762
794763 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
from line 766
797766
798767 - `type: "url"`
799768
800 - `"url"`
801
802769 - `url: string`
803770
804771 - `metadata: map[string]`
from line 844
877844
878845 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
879846
880 - `BetaManagedAgentsEffortLow object { type }`
847 - `BetaManagedAgentsEffortLow object`
881848
882849 Low effort. Favors latency over reasoning depth.
883850
884851 - `type: "low"`
885852
886 - `"low"`
887
888 - `BetaManagedAgentsEffortMedium object { type }`
853 - `BetaManagedAgentsEffortMedium object`
889854
890855 Medium effort. Balances latency and reasoning depth.
891856
892857 - `type: "medium"`
893858
894 - `"medium"`
895
896 - `BetaManagedAgentsEffortHigh object { type }`
859 - `BetaManagedAgentsEffortHigh object`
897860
898861 High effort. Favors reasoning depth.
899862
900863 - `type: "high"`
901864
902 - `"high"`
903
904 - `BetaManagedAgentsEffortXhigh object { type }`
865 - `BetaManagedAgentsEffortXhigh object`
905866
906867 Extra-high effort. Not all models accept this level.
907868
908869 - `type: "xhigh"`
909870
910 - `"xhigh"`
911
912 - `BetaManagedAgentsEffortMax object { type }`
871 - `BetaManagedAgentsEffortMax object`
913872
914873 Maximum effort. Favors reasoning depth over latency.
915874
916875 - `type: "max"`
917876
918 - `"max"`
919
920877 - `inference_geo: optional string`
921878
922879 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 894
937894
938895 Agents the coordinator may spawn as session threads, each resolved to a specific version.
939896
940 - `BetaManagedAgentsAgentReference object { id, type, version }`
897 - `BetaManagedAgentsAgentReference object`
941898
942899 A resolved agent reference with a concrete version.
943900
from line 902
945902
946903 - `type: "agent"`
947904
948 - `"agent"`
949
950905 - `version: number`
951906
952 - `BetaManagedAgentsAdvisor object { model, type }`
907 format: int32
908
909 - `BetaManagedAgentsAdvisor object`
953910
954911 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
955912
from line 916
959916
960917 - `type: "advisor"`
961918
962 - `"advisor"`
963
964919 - `type: "coordinator"`
965920
966 - `"coordinator"`
967
968921 - `name: string`
969922
970923 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
971924
972 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
925 - `BetaManagedAgentsAnthropicSkill object`
973926
974927 A resolved Anthropic-managed skill.
975928
from line 930
977930
978931 - `type: "anthropic"`
979932
980 - `"anthropic"`
981
982933 - `version: string`
983934
984 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
935 - `BetaManagedAgentsCustomSkill object`
985936
986937 A resolved user-created custom skill.
987938
from line 940
989940
990941 - `type: "custom"`
991942
992 - `"custom"`
993
994943 - `version: string`
995944
996945 - `system: string or null`
997946
998947 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
999948
1000 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
949 - `BetaManagedAgentsAgentToolset20260401 object`
1001950
1002951 - `configs: array of BetaManagedAgentsAgentToolConfig`
1003952
1004 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
953 - `BetaManagedAgentsBashToolConfig object`
1005954
1006955 Configuration for the bash tool.
1007956
from line 958
1009958
1010959 - `name: "bash"`
1011960
1012 - `"bash"`
1013
1014961 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1015962
1016963 Permission policy for tool execution.
1017964
1018 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
965 - `BetaManagedAgentsAlwaysAllowPolicy object`
1019966
1020967 Tool calls are automatically approved without user confirmation.
1021968
1022969 - `type: "always_allow"`
1023970
1024 - `"always_allow"`
1025
1026 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
971 - `BetaManagedAgentsAlwaysAskPolicy object`
1027972
1028973 Tool calls require user confirmation before execution.
1029974
1030975 - `type: "always_ask"`
1031976
1032 - `"always_ask"`
1033
1034977 - `type: "bash"`
1035978
1036 - `"bash"`
1037
1038 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
979 - `BetaManagedAgentsEditToolConfig object`
1039980
1040981 Configuration for the edit tool.
1041982
from line 984
1043984
1044985 - `name: "edit"`
1045986
1046 - `"edit"`
1047
1048987 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1049988
1050989 Permission policy for tool execution.
1051990
1052 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
991 - `BetaManagedAgentsAlwaysAllowPolicy object`
1053992
1054993 Tool calls are automatically approved without user confirmation.
1055994
1056 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
995 - `BetaManagedAgentsAlwaysAskPolicy object`
1057996
1058997 Tool calls require user confirmation before execution.
1059998
1060999 - `type: "edit"`
10611000
1062 - `"edit"`
1063
1064 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
1001 - `BetaManagedAgentsReadToolConfig object`
10651002
10661003 Configuration for the read tool.
10671004
from line 1006
10691006
10701007 - `name: "read"`
10711008
1072 - `"read"`
1073
10741009 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
10751010
10761011 Permission policy for tool execution.
10771012
1078 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1013 - `BetaManagedAgentsAlwaysAllowPolicy object`
10791014
10801015 Tool calls are automatically approved without user confirmation.
10811016
1082 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1017 - `BetaManagedAgentsAlwaysAskPolicy object`
10831018
10841019 Tool calls require user confirmation before execution.
10851020
10861021 - `type: "read"`
10871022
1088 - `"read"`
1089
1090 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
1023 - `BetaManagedAgentsWriteToolConfig object`
10911024
10921025 Configuration for the write tool.
10931026
from line 1028
10951028
10961029 - `name: "write"`
10971030
1098 - `"write"`
1099
11001031 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
11011032
11021033 Permission policy for tool execution.
11031034
1104 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1035 - `BetaManagedAgentsAlwaysAllowPolicy object`
11051036
11061037 Tool calls are automatically approved without user confirmation.
11071038
1108 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1039 - `BetaManagedAgentsAlwaysAskPolicy object`
11091040
11101041 Tool calls require user confirmation before execution.
11111042
11121043 - `type: "write"`
11131044
1114 - `"write"`
1115
1116 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
1045 - `BetaManagedAgentsGlobToolConfig object`
11171046
11181047 Configuration for the glob tool.
11191048
from line 1050
11211050
11221051 - `name: "glob"`
11231052
1124 - `"glob"`
1125
11261053 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
11271054
11281055 Permission policy for tool execution.
11291056
1130 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1057 - `BetaManagedAgentsAlwaysAllowPolicy object`
11311058
11321059 Tool calls are automatically approved without user confirmation.
11331060
1134 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1061 - `BetaManagedAgentsAlwaysAskPolicy object`
11351062
11361063 Tool calls require user confirmation before execution.
11371064
11381065 - `type: "glob"`
11391066
1140 - `"glob"`
1141
1142 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
1067 - `BetaManagedAgentsGrepToolConfig object`
11431068
11441069 Configuration for the grep tool.
11451070
from line 1072
11471072
11481073 - `name: "grep"`
11491074
1150 - `"grep"`
1151
11521075 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
11531076
11541077 Permission policy for tool execution.
11551078
1156 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1079 - `BetaManagedAgentsAlwaysAllowPolicy object`
11571080
11581081 Tool calls are automatically approved without user confirmation.
11591082
1160 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1083 - `BetaManagedAgentsAlwaysAskPolicy object`
11611084
11621085 Tool calls require user confirmation before execution.
11631086
11641087 - `type: "grep"`
11651088
1166 - `"grep"`
1167
1168 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
1089 - `BetaManagedAgentsWebFetchToolConfig object`
11691090
11701091 Configuration for the web_fetch tool.
11711092
from line 1094
11731094
11741095 - `name: "web_fetch"`
11751096
1176 - `"web_fetch"`
1177
11781097 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
11791098
11801099 Permission policy for tool execution.
11811100
1182 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1101 - `BetaManagedAgentsAlwaysAllowPolicy object`
11831102
11841103 Tool calls are automatically approved without user confirmation.
11851104
1186 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1105 - `BetaManagedAgentsAlwaysAskPolicy object`
11871106
11881107 Tool calls require user confirmation before execution.
11891108
11901109 - `type: "web_fetch"`
11911110
1192 - `"web_fetch"`
1193
11941111 - `allowed_domains: optional array of string`
11951112
11961113 - `blocked_domains: optional array of string`
11971114
11981115 - `max_content_tokens: optional number or null`
11991116
1200 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
1117 format: int32
1118
1119 - `BetaManagedAgentsWebSearchToolConfig object`
12011120
12021121 Configuration for the web_search tool.
12031122
from line 1124
12051124
12061125 - `name: "web_search"`
12071126
1208 - `"web_search"`
1209
12101127 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
12111128
12121129 Permission policy for tool execution.
12131130
1214 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1131 - `BetaManagedAgentsAlwaysAllowPolicy object`
12151132
12161133 Tool calls are automatically approved without user confirmation.
12171134
1218 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1135 - `BetaManagedAgentsAlwaysAskPolicy object`
12191136
12201137 Tool calls require user confirmation before execution.
12211138
12221139 - `type: "web_search"`
12231140
1224 - `"web_search"`
1225
12261141 - `allowed_domains: optional array of string`
12271142
12281143 - `blocked_domains: optional array of string`
from line 1150
12351150
12361151 Location precision. Only "approximate" is supported.
12371152
1238 - `"approximate"`
1239
12401153 - `city: optional string or null`
12411154
12421155 City name.
12431156
1157 minLength: 1, maxLength: 255
1158
12441159 - `country: optional string or null`
12451160
12461161 Two-letter ISO 3166-1 country code, uppercase.
from line 1164
12491164
12501165 Region or state name.
12511166
1167 minLength: 1, maxLength: 255
1168
12521169 - `timezone: optional string or null`
12531170
12541171 IANA timezone identifier, e.g. "America/Los_Angeles".
12551172
1173 minLength: 1, maxLength: 255
1174
12561175 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
12571176
12581177 Resolved default configuration for agent tools.
from line 1182
12631182
12641183 Permission policy for tool execution.
12651184
1266 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1185 - `BetaManagedAgentsAlwaysAllowPolicy object`
12671186
12681187 Tool calls are automatically approved without user confirmation.
12691188
1270 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1189 - `BetaManagedAgentsAlwaysAskPolicy object`
12711190
12721191 Tool calls require user confirmation before execution.
12731192
12741193 - `type: "agent_toolset_20260401"`
12751194
1276 - `"agent_toolset_20260401"`
1277
1278 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
1195 - `BetaManagedAgentsMCPToolset object`
12791196
12801197 - `configs: array of BetaManagedAgentsMCPToolConfig`
12811198
from line 1204
12871204
12881205 Permission policy for tool execution.
12891206
1290 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1207 - `BetaManagedAgentsAlwaysAllowPolicy object`
12911208
12921209 Tool calls are automatically approved without user confirmation.
12931210
1294 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1211 - `BetaManagedAgentsAlwaysAskPolicy object`
12951212
12961213 Tool calls require user confirmation before execution.
12971214
from line 1222
13051222
13061223 Permission policy for tool execution.
13071224
1308 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1225 - `BetaManagedAgentsAlwaysAllowPolicy object`
13091226
13101227 Tool calls are automatically approved without user confirmation.
13111228
1312 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1229 - `BetaManagedAgentsAlwaysAskPolicy object`
13131230
13141231 Tool calls require user confirmation before execution.
13151232
from line 1234
13171234
13181235 - `type: "mcp_toolset"`
13191236
1320 - `"mcp_toolset"`
1321
1322 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
1237 - `BetaManagedAgentsCustomTool object`
13231238
13241239 A custom tool as returned in API responses.
13251240
from line 1246
13311246
13321247 - `type: "object"`
13331248
1334 - `"object"`
1335
13361249 - `properties: optional map[unknown] or null`
13371250
13381251 - `required: optional array of string or null`
from line 1254
13411254
13421255 - `type: "custom"`
13431256
1344 - `"custom"`
1345
13461257 - `type: "agent"`
13471258
1348 - `"agent"`
1349
13501259 - `updated_at: string`
13511260
13521261 A timestamp in RFC 3339 format
13531262
1263 format: date-time
1264
13541265 - `version: number`
13551266
13561267 The agent's current version. Starts at 1 and increments when the agent is modified.
13571268
1269 format: int32
1270
13581271### Example
13591272
1360```http
1273```bash
13611274curl https://api.anthropic.com/v1/agents \
13621275 -H 'Content-Type: application/json' \
13631276 -H 'anthropic-version: 2023-06-01' \
from line 1292
13791292 }'
13801293```
13811294
1382#### Response
1295#### Response (200)
13831296
13841297```json
13851298{
from line 1371
14581371
14591372## List Agents
14601373
1461**get** `/v1/agents`
1374**GET** `/v1/agents`
14621375
14631376List Agents
14641377
1465### Query Parameters
1378### Query parameters
14661379
14671380- `"created_at[gte]": optional string`
14681381
14691382 Return agents created at or after this time (inclusive).
14701383
1384 format: date-time
1385
14711386- `"created_at[lte]": optional string`
14721387
14731388 Return agents created at or before this time (inclusive).
14741389
1390 format: date-time
1391
14751392- `include_archived: optional boolean`
14761393
14771394 Include archived agents in results. Defaults to false.
from line 1397
14801397
14811398 Maximum results per page. Default 20, maximum 100.
14821399
1400 format: int32
1401
14831402- `page: optional string`
14841403
14851404 Opaque pagination cursor from a previous response.
14861405
1487### Header Parameters
1406### Headers
14881407
14891408- `"anthropic-beta": optional array of AnthropicBeta`
14901409
from line 1493
15741493
15751494 A timestamp in RFC 3339 format
15761495
1496 format: date-time
1497
15771498 - `created_at: string`
15781499
15791500 A timestamp in RFC 3339 format
15801501
1502 format: date-time
1503
15811504 - `description: string or null`
15821505
15831506 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
from line 1509
15861509
15871510 - `type: "url"`
15881511
1589 - `"url"`
1590
15911512 - `url: string`
15921513
15931514 - `metadata: map[string]`
from line 1587
16661587
16671588 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
16681589
1669 - `BetaManagedAgentsEffortLow object { type }`
1590 - `BetaManagedAgentsEffortLow object`
16701591
16711592 Low effort. Favors latency over reasoning depth.
16721593
16731594 - `type: "low"`
16741595
1675 - `"low"`
1676
1677 - `BetaManagedAgentsEffortMedium object { type }`
1596 - `BetaManagedAgentsEffortMedium object`
16781597
16791598 Medium effort. Balances latency and reasoning depth.
16801599
16811600 - `type: "medium"`
16821601
1683 - `"medium"`
1684
1685 - `BetaManagedAgentsEffortHigh object { type }`
1602 - `BetaManagedAgentsEffortHigh object`
16861603
16871604 High effort. Favors reasoning depth.
16881605
16891606 - `type: "high"`
16901607
1691 - `"high"`
1692
1693 - `BetaManagedAgentsEffortXhigh object { type }`
1608 - `BetaManagedAgentsEffortXhigh object`
16941609
16951610 Extra-high effort. Not all models accept this level.
16961611
16971612 - `type: "xhigh"`
16981613
1699 - `"xhigh"`
1700
1701 - `BetaManagedAgentsEffortMax object { type }`
1614 - `BetaManagedAgentsEffortMax object`
17021615
17031616 Maximum effort. Favors reasoning depth over latency.
17041617
17051618 - `type: "max"`
17061619
1707 - `"max"`
1708
17091620 - `inference_geo: optional string`
17101621
17111622 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 1637
17261637
17271638 Agents the coordinator may spawn as session threads, each resolved to a specific version.
17281639
1729 - `BetaManagedAgentsAgentReference object { id, type, version }`
1640 - `BetaManagedAgentsAgentReference object`
17301641
17311642 A resolved agent reference with a concrete version.
17321643
from line 1645
17341645
17351646 - `type: "agent"`
17361647
1737 - `"agent"`
1738
17391648 - `version: number`
17401649
1741 - `BetaManagedAgentsAdvisor object { model, type }`
1650 format: int32
1651
1652 - `BetaManagedAgentsAdvisor object`
17421653
17431654 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
17441655
from line 1659
17481659
17491660 - `type: "advisor"`
17501661
1751 - `"advisor"`
1752
17531662 - `type: "coordinator"`
17541663
1755 - `"coordinator"`
1756
17571664 - `name: string`
17581665
17591666 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
17601667
1761 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
1668 - `BetaManagedAgentsAnthropicSkill object`
17621669
17631670 A resolved Anthropic-managed skill.
17641671
from line 1673
17661673
17671674 - `type: "anthropic"`
17681675
1769 - `"anthropic"`
1770
17711676 - `version: string`
17721677
1773 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
1678 - `BetaManagedAgentsCustomSkill object`
17741679
17751680 A resolved user-created custom skill.
17761681
from line 1683
17781683
17791684 - `type: "custom"`
17801685
1781 - `"custom"`
1782
17831686 - `version: string`
17841687
17851688 - `system: string or null`
17861689
17871690 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
17881691
1789 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
1692 - `BetaManagedAgentsAgentToolset20260401 object`
17901693
17911694 - `configs: array of BetaManagedAgentsAgentToolConfig`
17921695
1793 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
1696 - `BetaManagedAgentsBashToolConfig object`
17941697
17951698 Configuration for the bash tool.
17961699
from line 1701
17981701
17991702 - `name: "bash"`
18001703
1801 - `"bash"`
1802
18031704 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18041705
18051706 Permission policy for tool execution.
18061707
1807 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1708 - `BetaManagedAgentsAlwaysAllowPolicy object`
18081709
18091710 Tool calls are automatically approved without user confirmation.
18101711
18111712 - `type: "always_allow"`
18121713
1813 - `"always_allow"`
1814
1815 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1714 - `BetaManagedAgentsAlwaysAskPolicy object`
18161715
18171716 Tool calls require user confirmation before execution.
18181717
18191718 - `type: "always_ask"`
18201719
1821 - `"always_ask"`
1822
18231720 - `type: "bash"`
18241721
1825 - `"bash"`
1826
1827 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
1722 - `BetaManagedAgentsEditToolConfig object`
18281723
18291724 Configuration for the edit tool.
18301725
from line 1727
18321727
18331728 - `name: "edit"`
18341729
1835 - `"edit"`
1836
18371730 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18381731
18391732 Permission policy for tool execution.
18401733
1841 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1734 - `BetaManagedAgentsAlwaysAllowPolicy object`
18421735
18431736 Tool calls are automatically approved without user confirmation.
18441737
1845 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1738 - `BetaManagedAgentsAlwaysAskPolicy object`
18461739
18471740 Tool calls require user confirmation before execution.
18481741
18491742 - `type: "edit"`
18501743
1851 - `"edit"`
1852
1853 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
1744 - `BetaManagedAgentsReadToolConfig object`
18541745
18551746 Configuration for the read tool.
18561747
from line 1749
18581749
18591750 - `name: "read"`
18601751
1861 - `"read"`
1862
18631752 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18641753
18651754 Permission policy for tool execution.
18661755
1867 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1756 - `BetaManagedAgentsAlwaysAllowPolicy object`
18681757
18691758 Tool calls are automatically approved without user confirmation.
18701759
1871 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1760 - `BetaManagedAgentsAlwaysAskPolicy object`
18721761
18731762 Tool calls require user confirmation before execution.
18741763
18751764 - `type: "read"`
18761765
1877 - `"read"`
1878
1879 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
1766 - `BetaManagedAgentsWriteToolConfig object`
18801767
18811768 Configuration for the write tool.
18821769
from line 1771
18841771
18851772 - `name: "write"`
18861773
1887 - `"write"`
1888
18891774 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18901775
18911776 Permission policy for tool execution.
18921777
1893 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1778 - `BetaManagedAgentsAlwaysAllowPolicy object`
18941779
18951780 Tool calls are automatically approved without user confirmation.
18961781
1897 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1782 - `BetaManagedAgentsAlwaysAskPolicy object`
18981783
18991784 Tool calls require user confirmation before execution.
19001785
19011786 - `type: "write"`
19021787
1903 - `"write"`
1904
1905 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
1788 - `BetaManagedAgentsGlobToolConfig object`
19061789
19071790 Configuration for the glob tool.
19081791
from line 1793
19101793
19111794 - `name: "glob"`
19121795
1913 - `"glob"`
1914
19151796 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19161797
19171798 Permission policy for tool execution.
19181799
1919 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1800 - `BetaManagedAgentsAlwaysAllowPolicy object`
19201801
19211802 Tool calls are automatically approved without user confirmation.
19221803
1923 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1804 - `BetaManagedAgentsAlwaysAskPolicy object`
19241805
19251806 Tool calls require user confirmation before execution.
19261807
19271808 - `type: "glob"`
19281809
1929 - `"glob"`
1930
1931 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
1810 - `BetaManagedAgentsGrepToolConfig object`
19321811
19331812 Configuration for the grep tool.
19341813
from line 1815
19361815
19371816 - `name: "grep"`
19381817
1939 - `"grep"`
1940
19411818 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19421819
19431820 Permission policy for tool execution.
19441821
1945 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1822 - `BetaManagedAgentsAlwaysAllowPolicy object`
19461823
19471824 Tool calls are automatically approved without user confirmation.
19481825
1949 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1826 - `BetaManagedAgentsAlwaysAskPolicy object`
19501827
19511828 Tool calls require user confirmation before execution.
19521829
19531830 - `type: "grep"`
19541831
1955 - `"grep"`
1956
1957 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
1832 - `BetaManagedAgentsWebFetchToolConfig object`
19581833
19591834 Configuration for the web_fetch tool.
19601835
from line 1837
19621837
19631838 - `name: "web_fetch"`
19641839
1965 - `"web_fetch"`
1966
19671840 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19681841
19691842 Permission policy for tool execution.
19701843
1971 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1844 - `BetaManagedAgentsAlwaysAllowPolicy object`
19721845
19731846 Tool calls are automatically approved without user confirmation.
19741847
1975 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1848 - `BetaManagedAgentsAlwaysAskPolicy object`
19761849
19771850 Tool calls require user confirmation before execution.
19781851
19791852 - `type: "web_fetch"`
19801853
1981 - `"web_fetch"`
1982
19831854 - `allowed_domains: optional array of string`
19841855
19851856 - `blocked_domains: optional array of string`
19861857
19871858 - `max_content_tokens: optional number or null`
19881859
1989 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
1860 format: int32
1861
1862 - `BetaManagedAgentsWebSearchToolConfig object`
19901863
19911864 Configuration for the web_search tool.
19921865
from line 1867
19941867
19951868 - `name: "web_search"`
19961869
1997 - `"web_search"`
1998
19991870 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
20001871
20011872 Permission policy for tool execution.
20021873
2003 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1874 - `BetaManagedAgentsAlwaysAllowPolicy object`
20041875
20051876 Tool calls are automatically approved without user confirmation.
20061877
2007 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1878 - `BetaManagedAgentsAlwaysAskPolicy object`
20081879
20091880 Tool calls require user confirmation before execution.
20101881
20111882 - `type: "web_search"`
20121883
2013 - `"web_search"`
2014
20151884 - `allowed_domains: optional array of string`
20161885
20171886 - `blocked_domains: optional array of string`
from line 1893
20241893
20251894 Location precision. Only "approximate" is supported.
20261895
2027 - `"approximate"`
2028
20291896 - `city: optional string or null`
20301897
20311898 City name.
20321899
1900 minLength: 1, maxLength: 255
1901
20331902 - `country: optional string or null`
20341903
20351904 Two-letter ISO 3166-1 country code, uppercase.
from line 1907
20381907
20391908 Region or state name.
20401909
1910 minLength: 1, maxLength: 255
1911
20411912 - `timezone: optional string or null`
20421913
20431914 IANA timezone identifier, e.g. "America/Los_Angeles".
20441915
1916 minLength: 1, maxLength: 255
1917
20451918 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
20461919
20471920 Resolved default configuration for agent tools.
from line 1925
20521925
20531926 Permission policy for tool execution.
20541927
2055 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1928 - `BetaManagedAgentsAlwaysAllowPolicy object`
20561929
20571930 Tool calls are automatically approved without user confirmation.
20581931
2059 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1932 - `BetaManagedAgentsAlwaysAskPolicy object`
20601933
20611934 Tool calls require user confirmation before execution.
20621935
20631936 - `type: "agent_toolset_20260401"`
20641937
2065 - `"agent_toolset_20260401"`
2066
2067 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
1938 - `BetaManagedAgentsMCPToolset object`
20681939
20691940 - `configs: array of BetaManagedAgentsMCPToolConfig`
20701941
from line 1947
20761947
20771948 Permission policy for tool execution.
20781949
2079 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1950 - `BetaManagedAgentsAlwaysAllowPolicy object`
20801951
20811952 Tool calls are automatically approved without user confirmation.
20821953
2083 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1954 - `BetaManagedAgentsAlwaysAskPolicy object`
20841955
20851956 Tool calls require user confirmation before execution.
20861957
from line 1965
20941965
20951966 Permission policy for tool execution.
20961967
2097 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1968 - `BetaManagedAgentsAlwaysAllowPolicy object`
20981969
20991970 Tool calls are automatically approved without user confirmation.
21001971
2101 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1972 - `BetaManagedAgentsAlwaysAskPolicy object`
21021973
21031974 Tool calls require user confirmation before execution.
21041975
from line 1977
21061977
21071978 - `type: "mcp_toolset"`
21081979
2109 - `"mcp_toolset"`
2110
2111 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
1980 - `BetaManagedAgentsCustomTool object`
21121981
21131982 A custom tool as returned in API responses.
21141983
from line 1989
21201989
21211990 - `type: "object"`
21221991
2123 - `"object"`
2124
21251992 - `properties: optional map[unknown] or null`
21261993
21271994 - `required: optional array of string or null`
from line 1997
21301997
21311998 - `type: "custom"`
21321999
2133 - `"custom"`
2134
21352000 - `type: "agent"`
21362001
2137 - `"agent"`
2138
21392002 - `updated_at: string`
21402003
21412004 A timestamp in RFC 3339 format
21422005
2006 format: date-time
2007
21432008 - `version: number`
21442009
21452010 The agent's current version. Starts at 1 and increments when the agent is modified.
21462011
2012 format: int32
2013
21472014- `next_page: optional string or null`
21482015
21492016 Opaque cursor for the next page. Null when no more results.
21502017
21512018### Example
21522019
2153```http
2020```bash
21542021curl https://api.anthropic.com/v1/agents \
21552022 -H 'anthropic-version: 2023-06-01' \
21562023 -H 'anthropic-beta: managed-agents-2026-04-01' \
21572024 -H "X-Api-Key: $ANTHROPIC_API_KEY"
21582025```
21592026
2160#### Response
2027#### Response (200)
21612028
21622029```json
21632030{
from line 2108
22412108
22422109## Get Agent
22432110
2244**get** `/v1/agents/{agent_id}`
2111**GET** `/v1/agents/{agent_id}`
22452112
22462113Get Agent
22472114
2248### Path Parameters
2115### Path parameters
22492116
22502117- `agent_id: string`
22512118
2252### Query Parameters
2119### Query parameters
22532120
22542121- `version: optional number`
22552122
22562123 Agent version. Omit for the most recent version. Must be at least 1 if specified.
22572124
2258### Header Parameters
2125 format: int32
2126
2127### Headers
22592128
22602129- `"anthropic-beta": optional array of AnthropicBeta`
22612130
from line 2204
23352204
23362205### Returns
23372206
2338- `BetaManagedAgentsAgent object { id, archived_at, created_at, 12 more }`
2207- `BetaManagedAgentsAgent object`
23392208
23402209 A Managed Agents `agent`.
23412210
from line 2214
23452214
23462215 A timestamp in RFC 3339 format
23472216
2217 format: date-time
2218
23482219 - `created_at: string`
23492220
23502221 A timestamp in RFC 3339 format
23512222
2223 format: date-time
2224
23522225 - `description: string or null`
23532226
23542227 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
from line 2230
23572230
23582231 - `type: "url"`
23592232
2360 - `"url"`
2361
23622233 - `url: string`
23632234
23642235 - `metadata: map[string]`
from line 2308
24372308
24382309 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
24392310
2440 - `BetaManagedAgentsEffortLow object { type }`
2311 - `BetaManagedAgentsEffortLow object`
24412312
24422313 Low effort. Favors latency over reasoning depth.
24432314
24442315 - `type: "low"`
24452316
2446 - `"low"`
2447
2448 - `BetaManagedAgentsEffortMedium object { type }`
2317 - `BetaManagedAgentsEffortMedium object`
24492318
24502319 Medium effort. Balances latency and reasoning depth.
24512320
24522321 - `type: "medium"`
24532322
2454 - `"medium"`
2455
2456 - `BetaManagedAgentsEffortHigh object { type }`
2323 - `BetaManagedAgentsEffortHigh object`
24572324
24582325 High effort. Favors reasoning depth.
24592326
24602327 - `type: "high"`
24612328
2462 - `"high"`
2463
2464 - `BetaManagedAgentsEffortXhigh object { type }`
2329 - `BetaManagedAgentsEffortXhigh object`
24652330
24662331 Extra-high effort. Not all models accept this level.
24672332
24682333 - `type: "xhigh"`
24692334
2470 - `"xhigh"`
2471
2472 - `BetaManagedAgentsEffortMax object { type }`
2335 - `BetaManagedAgentsEffortMax object`
24732336
24742337 Maximum effort. Favors reasoning depth over latency.
24752338
24762339 - `type: "max"`
24772340
2478 - `"max"`
2479
24802341 - `inference_geo: optional string`
24812342
24822343 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 2358
24972358
24982359 Agents the coordinator may spawn as session threads, each resolved to a specific version.
24992360
2500 - `BetaManagedAgentsAgentReference object { id, type, version }`
2361 - `BetaManagedAgentsAgentReference object`
25012362
25022363 A resolved agent reference with a concrete version.
25032364
from line 2366
25052366
25062367 - `type: "agent"`
25072368
2508 - `"agent"`
2509
25102369 - `version: number`
25112370
2512 - `BetaManagedAgentsAdvisor object { model, type }`
2371 format: int32
2372
2373 - `BetaManagedAgentsAdvisor object`
25132374
25142375 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
25152376
from line 2380
25192380
25202381 - `type: "advisor"`
25212382
2522 - `"advisor"`
2523
25242383 - `type: "coordinator"`
25252384
2526 - `"coordinator"`
2527
25282385 - `name: string`
25292386
25302387 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
25312388
2532 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
2389 - `BetaManagedAgentsAnthropicSkill object`
25332390
25342391 A resolved Anthropic-managed skill.
25352392
from line 2394
25372394
25382395 - `type: "anthropic"`
25392396
2540 - `"anthropic"`
2541
25422397 - `version: string`
25432398
2544 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
2399 - `BetaManagedAgentsCustomSkill object`
25452400
25462401 A resolved user-created custom skill.
25472402
from line 2404
25492404
25502405 - `type: "custom"`
25512406
2552 - `"custom"`
2553
25542407 - `version: string`
25552408
25562409 - `system: string or null`
25572410
25582411 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
25592412
2560 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
2413 - `BetaManagedAgentsAgentToolset20260401 object`
25612414
25622415 - `configs: array of BetaManagedAgentsAgentToolConfig`
25632416
2564 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
2417 - `BetaManagedAgentsBashToolConfig object`
25652418
25662419 Configuration for the bash tool.
25672420
from line 2422
25692422
25702423 - `name: "bash"`
25712424
2572 - `"bash"`
2573
25742425 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
25752426
25762427 Permission policy for tool execution.
25772428
2578 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2429 - `BetaManagedAgentsAlwaysAllowPolicy object`
25792430
25802431 Tool calls are automatically approved without user confirmation.
25812432
25822433 - `type: "always_allow"`
25832434
2584 - `"always_allow"`
2585
2586 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2435 - `BetaManagedAgentsAlwaysAskPolicy object`
25872436
25882437 Tool calls require user confirmation before execution.
25892438
25902439 - `type: "always_ask"`
25912440
2592 - `"always_ask"`
2593
25942441 - `type: "bash"`
25952442
2596 - `"bash"`
2597
2598 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
2443 - `BetaManagedAgentsEditToolConfig object`
25992444
26002445 Configuration for the edit tool.
26012446
from line 2448
26032448
26042449 - `name: "edit"`
26052450
2606 - `"edit"`
2607
26082451 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
26092452
26102453 Permission policy for tool execution.
26112454
2612 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2455 - `BetaManagedAgentsAlwaysAllowPolicy object`
26132456
26142457 Tool calls are automatically approved without user confirmation.
26152458
2616 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2459 - `BetaManagedAgentsAlwaysAskPolicy object`
26172460
26182461 Tool calls require user confirmation before execution.
26192462
26202463 - `type: "edit"`
26212464
2622 - `"edit"`
2623
2624 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
2465 - `BetaManagedAgentsReadToolConfig object`
26252466
26262467 Configuration for the read tool.
26272468
from line 2470
26292470
26302471 - `name: "read"`
26312472
2632 - `"read"`
2633
26342473 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
26352474
26362475 Permission policy for tool execution.
26372476
2638 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2477 - `BetaManagedAgentsAlwaysAllowPolicy object`
26392478
26402479 Tool calls are automatically approved without user confirmation.
26412480
2642 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2481 - `BetaManagedAgentsAlwaysAskPolicy object`
26432482
26442483 Tool calls require user confirmation before execution.
26452484
26462485 - `type: "read"`
26472486
2648 - `"read"`
2649
2650 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
2487 - `BetaManagedAgentsWriteToolConfig object`
26512488
26522489 Configuration for the write tool.
26532490
from line 2492
26552492
26562493 - `name: "write"`
26572494
2658 - `"write"`
2659
26602495 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
26612496
26622497 Permission policy for tool execution.
26632498
2664 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2499 - `BetaManagedAgentsAlwaysAllowPolicy object`
26652500
26662501 Tool calls are automatically approved without user confirmation.
26672502
2668 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2503 - `BetaManagedAgentsAlwaysAskPolicy object`
26692504
26702505 Tool calls require user confirmation before execution.
26712506
26722507 - `type: "write"`
26732508
2674 - `"write"`
2675
2676 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
2509 - `BetaManagedAgentsGlobToolConfig object`
26772510
26782511 Configuration for the glob tool.
26792512
from line 2514
26812514
26822515 - `name: "glob"`
26832516
2684 - `"glob"`
2685
26862517 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
26872518
26882519 Permission policy for tool execution.
26892520
2690 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2521 - `BetaManagedAgentsAlwaysAllowPolicy object`
26912522
26922523 Tool calls are automatically approved without user confirmation.
26932524
2694 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2525 - `BetaManagedAgentsAlwaysAskPolicy object`
26952526
26962527 Tool calls require user confirmation before execution.
26972528
26982529 - `type: "glob"`
26992530
2700 - `"glob"`
2701
2702 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
2531 - `BetaManagedAgentsGrepToolConfig object`
27032532
27042533 Configuration for the grep tool.
27052534
from line 2536
27072536
27082537 - `name: "grep"`
27092538
2710 - `"grep"`
2711
27122539 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
27132540
27142541 Permission policy for tool execution.
27152542
2716 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2543 - `BetaManagedAgentsAlwaysAllowPolicy object`
27172544
27182545 Tool calls are automatically approved without user confirmation.
27192546
2720 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2547 - `BetaManagedAgentsAlwaysAskPolicy object`
27212548
27222549 Tool calls require user confirmation before execution.
27232550
27242551 - `type: "grep"`
27252552
2726 - `"grep"`
2727
2728 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
2553 - `BetaManagedAgentsWebFetchToolConfig object`
27292554
27302555 Configuration for the web_fetch tool.
27312556
from line 2558
27332558
27342559 - `name: "web_fetch"`
27352560
2736 - `"web_fetch"`
2737
27382561 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
27392562
27402563 Permission policy for tool execution.
27412564
2742 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2565 - `BetaManagedAgentsAlwaysAllowPolicy object`
27432566
27442567 Tool calls are automatically approved without user confirmation.
27452568
2746 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2569 - `BetaManagedAgentsAlwaysAskPolicy object`
27472570
27482571 Tool calls require user confirmation before execution.
27492572
27502573 - `type: "web_fetch"`
27512574
2752 - `"web_fetch"`
2753
27542575 - `allowed_domains: optional array of string`
27552576
27562577 - `blocked_domains: optional array of string`
27572578
27582579 - `max_content_tokens: optional number or null`
27592580
2760 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
2581 format: int32
2582
2583 - `BetaManagedAgentsWebSearchToolConfig object`
27612584
27622585 Configuration for the web_search tool.
27632586
from line 2588
27652588
27662589 - `name: "web_search"`
27672590
2768 - `"web_search"`
2769
27702591 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
27712592
27722593 Permission policy for tool execution.
27732594
2774 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2595 - `BetaManagedAgentsAlwaysAllowPolicy object`
27752596
27762597 Tool calls are automatically approved without user confirmation.
27772598
2778 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2599 - `BetaManagedAgentsAlwaysAskPolicy object`
27792600
27802601 Tool calls require user confirmation before execution.
27812602
27822603 - `type: "web_search"`
27832604
2784 - `"web_search"`
2785
27862605 - `allowed_domains: optional array of string`
27872606
27882607 - `blocked_domains: optional array of string`
from line 2614
27952614
27962615 Location precision. Only "approximate" is supported.
27972616
2798 - `"approximate"`
2799
28002617 - `city: optional string or null`
28012618
28022619 City name.
28032620
2621 minLength: 1, maxLength: 255
2622
28042623 - `country: optional string or null`
28052624
28062625 Two-letter ISO 3166-1 country code, uppercase.
from line 2628
28092628
28102629 Region or state name.
28112630
2631 minLength: 1, maxLength: 255
2632
28122633 - `timezone: optional string or null`
28132634
28142635 IANA timezone identifier, e.g. "America/Los_Angeles".
28152636
2637 minLength: 1, maxLength: 255
2638
28162639 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
28172640
28182641 Resolved default configuration for agent tools.
from line 2646
28232646
28242647 Permission policy for tool execution.
28252648
2826 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2649 - `BetaManagedAgentsAlwaysAllowPolicy object`
28272650
28282651 Tool calls are automatically approved without user confirmation.
28292652
2830 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2653 - `BetaManagedAgentsAlwaysAskPolicy object`
28312654
28322655 Tool calls require user confirmation before execution.
28332656
28342657 - `type: "agent_toolset_20260401"`
28352658
2836 - `"agent_toolset_20260401"`
2837
2838 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
2659 - `BetaManagedAgentsMCPToolset object`
28392660
28402661 - `configs: array of BetaManagedAgentsMCPToolConfig`
28412662
from line 2668
28472668
28482669 Permission policy for tool execution.
28492670
2850 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2671 - `BetaManagedAgentsAlwaysAllowPolicy object`
28512672
28522673 Tool calls are automatically approved without user confirmation.
28532674
2854 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2675 - `BetaManagedAgentsAlwaysAskPolicy object`
28552676
28562677 Tool calls require user confirmation before execution.
28572678
from line 2686
28652686
28662687 Permission policy for tool execution.
28672688
2868 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2689 - `BetaManagedAgentsAlwaysAllowPolicy object`
28692690
28702691 Tool calls are automatically approved without user confirmation.
28712692
2872 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2693 - `BetaManagedAgentsAlwaysAskPolicy object`
28732694
28742695 Tool calls require user confirmation before execution.
28752696
from line 2698
28772698
28782699 - `type: "mcp_toolset"`
28792700
2880 - `"mcp_toolset"`
2881
2882 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
2701 - `BetaManagedAgentsCustomTool object`
28832702
28842703 A custom tool as returned in API responses.
28852704
from line 2710
28912710
28922711 - `type: "object"`
28932712
2894 - `"object"`
2895
28962713 - `properties: optional map[unknown] or null`
28972714
28982715 - `required: optional array of string or null`
from line 2718
29012718
29022719 - `type: "custom"`
29032720
2904 - `"custom"`
2905
29062721 - `type: "agent"`
29072722
2908 - `"agent"`
2909
29102723 - `updated_at: string`
29112724
29122725 A timestamp in RFC 3339 format
29132726
2727 format: date-time
2728
29142729 - `version: number`
29152730
29162731 The agent's current version. Starts at 1 and increments when the agent is modified.
29172732
2733 format: int32
2734
29182735### Example
29192736
2920```http
2737```bash
29212738curl https://api.anthropic.com/v1/agents/$AGENT_ID \
29222739 -H 'anthropic-version: 2023-06-01' \
29232740 -H 'anthropic-beta: managed-agents-2026-04-01' \
29242741 -H "X-Api-Key: $ANTHROPIC_API_KEY"
29252742```
29262743
2927#### Response
2744#### Response (200)
29282745
29292746```json
29302747{
from line 2820
30032820
30042821## Update Agent
30052822
3006**post** `/v1/agents/{agent_id}`
2823**POST** `/v1/agents/{agent_id}`
30072824
30082825Update Agent
30092826
3010### Path Parameters
2827### Path parameters
30112828
30122829- `agent_id: string`
30132830
3014### Header Parameters
2831### Headers
30152832
30162833- `"anthropic-beta": optional array of AnthropicBeta`
30172834
from line 2906
30892906
30902907 - `"mid-conversation-tool-changes-2026-07-01"`
30912908
3092### Body Parameters
2909### Body parameters
30932910
30942911- `description: optional string or null`
30952912
30962913 Description. Omit to preserve; send empty string or null to clear.
30972914
2915 maxLength: 2048
2916
30982917- `mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams or null`
30992918
31002919 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).
from line 2922
31032922
31042923 Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.
31052924
2925 minLength: 1, maxLength: 255
2926
31062927 - `type: "url"`
31072928
3108 - `"url"`
3109
31102929 - `url: string`
31112930
31122931 Endpoint URL for the MCP server.
31132932
2933 maxLength: 2048
2934
31142935- `metadata: optional map[string] or null`
31152936
31162937 Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars.
from line 3006
31853006
31863007 - `string`
31873008
3188 - `BetaManagedAgentsModelConfigParams object { id, effort, inference_geo, speed }`
3009 - `BetaManagedAgentsModelConfigParams object`
31893010
31903011 An object that defines additional configuration control over model use
31913012
from line 3034
32133034
32143035 - `"max"`
32153036
3216 - `BetaManagedAgentsEffortLow object { type }`
3037 - `BetaManagedAgentsEffortLow object`
32173038
32183039 Low effort. Favors latency over reasoning depth.
32193040
32203041 - `type: "low"`
32213042
3222 - `"low"`
3223
3224 - `BetaManagedAgentsEffortMedium object { type }`
3043 - `BetaManagedAgentsEffortMedium object`
32253044
32263045 Medium effort. Balances latency and reasoning depth.
32273046
32283047 - `type: "medium"`
32293048
3230 - `"medium"`
3231
3232 - `BetaManagedAgentsEffortHigh object { type }`
3049 - `BetaManagedAgentsEffortHigh object`
32333050
32343051 High effort. Favors reasoning depth.
32353052
32363053 - `type: "high"`
32373054
3238 - `"high"`
3239
3240 - `BetaManagedAgentsEffortXhigh object { type }`
3055 - `BetaManagedAgentsEffortXhigh object`
32413056
32423057 Extra-high effort. Not all models accept this level.
32433058
32443059 - `type: "xhigh"`
32453060
3246 - `"xhigh"`
3247
3248 - `BetaManagedAgentsEffortMax object { type }`
3061 - `BetaManagedAgentsEffortMax object`
32493062
32503063 Maximum effort. Favors reasoning depth over latency.
32513064
32523065 - `type: "max"`
32533066
3254 - `"max"`
3255
32563067 - `inference_geo: optional string or null`
32573068
32583069 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. On update, `model` is whole-object replacement — omitting inference_geo clears it.
from line 3086
32753086
32763087 - `string`
32773088
3278 - `BetaManagedAgentsAgentParams object { id, type, version }`
3089 - `BetaManagedAgentsAgentParams object`
32793090
32803091 Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version
32813092
from line 3094
32833094
32843095 The `agent` ID.
32853096
3097 minLength: 1, maxLength: 128
3098
32863099 - `type: "agent"`
32873100
3288 - `"agent"`
3289
32903101 - `version: optional number`
32913102
32923103 The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.
32933104
3294 - `BetaManagedAgentsMultiagentSelfParams object { type }`
3105 format: int32
3106
3107 - `BetaManagedAgentsMultiagentSelfParams object`
32953108
32963109 Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference.
32973110
32983111 - `type: "self"`
32993112
3300 - `"self"`
3301
3302 - `BetaManagedAgentsAdvisorParams object { model, type }`
3113 - `BetaManagedAgentsAdvisorParams object`
33033114
33043115 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`.
33053116
from line 3118
33073118
33083119 A Claude model id. The model must be permitted as an advisor for this agent's model — see the sessions/threads/advisor spec.
33093120
3121 minLength: 1, maxLength: 256
3122
33103123 - `type: "advisor"`
33113124
3312 - `"advisor"`
3313
33143125 - `type: "coordinator"`
33153126
3316 - `"coordinator"`
3317
33183127- `name: optional string`
33193128
33203129 Human-readable name. Must be non-empty. Omit to preserve. Cannot be cleared.
33213130
3131 maxLength: 256
3132
33223133- `skills: optional array of BetaManagedAgentsSkillParams or null`
33233134
33243135 Skills. Full replacement. Omit to preserve; send empty array or null to clear.
33253136
3326 - `BetaManagedAgentsAnthropicSkillParams object { skill_id, type, version }`
3137 - `BetaManagedAgentsAnthropicSkillParams object`
33273138
33283139 An Anthropic-managed skill.
33293140
from line 3142
33313142
33323143 Identifier of the Anthropic skill (e.g., "xlsx").
33333144
3145 minLength: 1, maxLength: 64
3146
33343147 - `type: "anthropic"`
33353148
3336 - `"anthropic"`
3337
33383149 - `version: optional string or null`
33393150
33403151 Version to pin. Defaults to latest if omitted.
33413152
3342 - `BetaManagedAgentsCustomSkillParams object { skill_id, type, version }`
3153 minLength: 1, maxLength: 64
3154
3155 - `BetaManagedAgentsCustomSkillParams object`
33433156
33443157 A user-created custom skill.
33453158
from line 3160
33473160
33483161 Tagged ID of the custom skill (e.g., "skill_01XJ5...").
33493162
3163 minLength: 1, maxLength: 64
3164
33503165 - `type: "custom"`
33513166
3352 - `"custom"`
3353
33543167 - `version: optional string or null`
33553168
33563169 Version to pin. Defaults to latest if omitted.
33573170
3171 minLength: 1, maxLength: 64
3172
33583173- `system: optional string or null`
33593174
33603175 System prompt. Omit to preserve; send empty string or null to clear.
33613176
3177 maxLength: 100000
3178
33623179- `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams or null`
33633180
33643181 Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed.
33653182
3366 - `BetaManagedAgentsAgentToolset20260401Params object { type, configs, default_config }`
3183 - `BetaManagedAgentsAgentToolset20260401Params object`
33673184
33683185 Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.
33693186
33703187 - `type: "agent_toolset_20260401"`
33713188
3372 - `"agent_toolset_20260401"`
3373
33743189 - `configs: optional array of BetaManagedAgentsAgentToolConfigParams`
33753190
33763191 Per-tool configuration overrides.
33773192
3378 - `BetaManagedAgentsBashToolConfigParams object { name, enabled, permission_policy, type }`
3193 - `BetaManagedAgentsBashToolConfigParams object`
33793194
33803195 Configuration override for the bash tool.
33813196
from line 3198
33833198
33843199 Must be "bash".
33853200
3386 - `"bash"`
3387
33883201 - `enabled: optional boolean or null`
33893202
33903203 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 3206
33933206
33943207 Permission policy for tool execution.
33953208
3396 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
3209 - `BetaManagedAgentsAlwaysAllowPolicy object`
33973210
33983211 Tool calls are automatically approved without user confirmation.
33993212
34003213 - `type: "always_allow"`
34013214
3402 - `"always_allow"`
3403
3404 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
3215 - `BetaManagedAgentsAlwaysAskPolicy object`
34053216
34063217 Tool calls require user confirmation before execution.
34073218
34083219 - `type: "always_ask"`
34093220
3410 - `"always_ask"`
3411
34123221 - `type: optional "bash"`
34133222
3414 - `"bash"`
3415
3416 - `BetaManagedAgentsEditToolConfigParams object { name, enabled, permission_policy, type }`
3223 - `BetaManagedAgentsEditToolConfigParams object`
34173224
34183225 Configuration override for the edit tool.
34193226
from line 3228
34213228
34223229 Must be "edit".
34233230
3424 - `"edit"`
3425
34263231 - `enabled: optional boolean or null`
34273232
34283233 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 3236
34313236
34323237 Permission policy for tool execution.
34333238
3434 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
3239 - `BetaManagedAgentsAlwaysAllowPolicy object`
34353240
34363241 Tool calls are automatically approved without user confirmation.
34373242
3438 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
3243 - `BetaManagedAgentsAlwaysAskPolicy object`
34393244
34403245 Tool calls require user confirmation before execution.
34413246
34423247 - `type: optional "edit"`
34433248
3444 - `"edit"`
3445
3446 - `BetaManagedAgentsReadToolConfigParams object { name, enabled, permission_policy, type }`
3249 - `BetaManagedAgentsReadToolConfigParams object`
34473250
34483251 Configuration override for the read tool.
34493252
from line 3254
34513254
34523255 Must be "read".
34533256
3454 - `"read"`
3455
34563257 - `enabled: optional boolean or null`
34573258
34583259 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 3262
34613262
34623263 Permission policy for tool execution.
34633264
3464 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
3265 - `BetaManagedAgentsAlwaysAllowPolicy object`
34653266
34663267 Tool calls are automatically approved without user confirmation.
34673268
3468 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
3269 - `BetaManagedAgentsAlwaysAskPolicy object`
34693270
34703271 Tool calls require user confirmation before execution.
34713272
34723273 - `type: optional "read"`
34733274
3474 - `"read"`
3475
3476 - `BetaManagedAgentsWriteToolConfigParams object { name, enabled, permission_policy, type }`
3275 - `BetaManagedAgentsWriteToolConfigParams object`
34773276
34783277 Configuration override for the write tool.
34793278
from line 3280
34813280
34823281 Must be "write".
34833282
3484 - `"write"`
3485
34863283 - `enabled: optional boolean or null`
34873284
34883285 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 3288
34913288
34923289 Permission policy for tool execution.
34933290
3494 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
3291 - `BetaManagedAgentsAlwaysAllowPolicy object`
34953292
34963293 Tool calls are automatically approved without user confirmation.
34973294
3498 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
3295 - `BetaManagedAgentsAlwaysAskPolicy object`
34993296
35003297 Tool calls require user confirmation before execution.
35013298
35023299 - `type: optional "write"`
35033300
3504 - `"write"`
3505
3506 - `BetaManagedAgentsGlobToolConfigParams object { name, enabled, permission_policy, type }`
3301 - `BetaManagedAgentsGlobToolConfigParams object`
35073302
35083303 Configuration override for the glob tool.
35093304
from line 3306
35113306
35123307 Must be "glob".
35133308
3514 - `"glob"`
3515
35163309 - `enabled: optional boolean or null`
35173310
35183311 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 3314
35213314
35223315 Permission policy for tool execution.
35233316
3524 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
3317 - `BetaManagedAgentsAlwaysAllowPolicy object`
35253318
35263319 Tool calls are automatically approved without user confirmation.
35273320
3528 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
3321 - `BetaManagedAgentsAlwaysAskPolicy object`
35293322
35303323 Tool calls require user confirmation before execution.
35313324
35323325 - `type: optional "glob"`
35333326
3534 - `"glob"`
3535
3536 - `BetaManagedAgentsGrepToolConfigParams object { name, enabled, permission_policy, type }`
3327 - `BetaManagedAgentsGrepToolConfigParams object`
35373328
35383329 Configuration override for the grep tool.
35393330
from line 3332
35413332
35423333 Must be "grep".
35433334
3544 - `"grep"`
3545
35463335 - `enabled: optional boolean or null`
35473336
35483337 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 3340
35513340
35523341 Permission policy for tool execution.
35533342
3554 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
3343 - `BetaManagedAgentsAlwaysAllowPolicy object`
35553344
35563345 Tool calls are automatically approved without user confirmation.
35573346
3558 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
3347 - `BetaManagedAgentsAlwaysAskPolicy object`
35593348
35603349 Tool calls require user confirmation before execution.
35613350
35623351 - `type: optional "grep"`
35633352
3564 - `"grep"`
3565
3566 - `BetaManagedAgentsWebFetchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }`
3353 - `BetaManagedAgentsWebFetchToolConfigParams object`
35673354
35683355 Configuration override for the web_fetch tool.
35693356
from line 3358
35713358
35723359 Must be "web_fetch".
35733360
3574 - `"web_fetch"`
3575
35763361 - `allowed_domains: optional array of string`
35773362
35783363 Only fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
from line 3374
35893374
35903375 Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs.
35913376
3377 format: int32
3378
35923379 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
35933380
35943381 Permission policy for tool execution.
35953382
3596 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
3383 - `BetaManagedAgentsAlwaysAllowPolicy object`
35973384
35983385 Tool calls are automatically approved without user confirmation.
35993386
3600 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
3387 - `BetaManagedAgentsAlwaysAskPolicy object`
36013388
36023389 Tool calls require user confirmation before execution.
36033390
36043391 - `type: optional "web_fetch"`
36053392
3606 - `"web_fetch"`
3607
3608 - `BetaManagedAgentsWebSearchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }`
3393 - `BetaManagedAgentsWebSearchToolConfigParams object`
36093394
36103395 Configuration override for the web_search tool.
36113396
from line 3398
36133398
36143399 Must be "web_search".
36153400
3616 - `"web_search"`
3617
36183401 - `allowed_domains: optional array of string`
36193402
36203403 Only return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
from line 3414
36313414
36323415 Permission policy for tool execution.
36333416
3634 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
3417 - `BetaManagedAgentsAlwaysAllowPolicy object`
36353418
36363419 Tool calls are automatically approved without user confirmation.
36373420
3638 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
3421 - `BetaManagedAgentsAlwaysAskPolicy object`
36393422
36403423 Tool calls require user confirmation before execution.
36413424
36423425 - `type: optional "web_search"`
36433426
3644 - `"web_search"`
3645
36463427 - `user_location: optional BetaManagedAgentsUserLocation or null`
36473428
36483429 Approximate user location for search result localization.
from line 3432
36513432
36523433 Location precision. Only "approximate" is supported.
36533434
3654 - `"approximate"`
3655
36563435 - `city: optional string or null`
36573436
36583437 City name.
36593438
3439 minLength: 1, maxLength: 255
3440
36603441 - `country: optional string or null`
36613442
36623443 Two-letter ISO 3166-1 country code, uppercase.
from line 3446
36653446
36663447 Region or state name.
36673448
3449 minLength: 1, maxLength: 255
3450
36683451 - `timezone: optional string or null`
36693452
36703453 IANA timezone identifier, e.g. "America/Los_Angeles".
36713454
3455 minLength: 1, maxLength: 255
3456
36723457 - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or null`
36733458
36743459 Default configuration for all tools in a toolset.
from line 3466
36813466
36823467 Permission policy for tool execution.
36833468
3684 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
3469 - `BetaManagedAgentsAlwaysAllowPolicy object`
36853470
36863471 Tool calls are automatically approved without user confirmation.
36873472
3688 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
3473 - `BetaManagedAgentsAlwaysAskPolicy object`
36893474
36903475 Tool calls require user confirmation before execution.
36913476
3692 - `BetaManagedAgentsMCPToolsetParams object { mcp_server_name, type, configs, default_config }`
3477 - `BetaManagedAgentsMCPToolsetParams object`
36933478
36943479 Configuration for tools from an MCP server defined in `mcp_servers`.
36953480
from line 3482
36973482
36983483 Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.
36993484
3485 minLength: 1, maxLength: 255
3486
37003487 - `type: "mcp_toolset"`
37013488
3702 - `"mcp_toolset"`
3703
37043489 - `configs: optional array of BetaManagedAgentsMCPToolConfigParams`
37053490
37063491 Per-tool configuration overrides.
from line 3494
37093494
37103495 Name of the MCP tool to configure. 1-128 characters.
37113496
3497 minLength: 1, maxLength: 128
3498
37123499 - `enabled: optional boolean or null`
37133500
37143501 Whether this tool is enabled. Overrides the `default_config` setting.
from line 3504
37173504
37183505 Permission policy for tool execution.
37193506
3720 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
3507 - `BetaManagedAgentsAlwaysAllowPolicy object`
37213508
37223509 Tool calls are automatically approved without user confirmation.
37233510
3724 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
3511 - `BetaManagedAgentsAlwaysAskPolicy object`
37253512
37263513 Tool calls require user confirmation before execution.
37273514
from line 3524
37373524
37383525 Permission policy for tool execution.
37393526
3740 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
3527 - `BetaManagedAgentsAlwaysAllowPolicy object`
37413528
37423529 Tool calls are automatically approved without user confirmation.
37433530
3744 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
3531 - `BetaManagedAgentsAlwaysAskPolicy object`
37453532
37463533 Tool calls require user confirmation before execution.
37473534
3748 - `BetaManagedAgentsCustomToolParams object { description, input_schema, name, type }`
3535 - `BetaManagedAgentsCustomToolParams object`
37493536
37503537 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.
37513538
from line 3540
37533540
37543541 Description of what the tool does, shown to the agent to help it decide when to use the tool.
37553542
3543 minLength: 1
3544
37563545 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
37573546
37583547 JSON Schema for custom tool input parameters.
37593548
37603549 - `type: "object"`
37613550
3762 - `"object"`
3763
37643551 - `properties: optional map[unknown] or null`
37653552
37663553 - `required: optional array of string or null`
from line 3556
37693556
37703557 Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.
37713558
3559 minLength: 1, maxLength: 128
3560
37723561 - `type: "custom"`
37733562
3774 - `"custom"`
3775
37763563- `version: optional number`
37773564
37783565 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.
37793566
3567 format: int32
3568
37803569### Returns
37813570
3782- `BetaManagedAgentsAgent object { id, archived_at, created_at, 12 more }`
3571- `BetaManagedAgentsAgent object`
37833572
37843573 A Managed Agents `agent`.
37853574
from line 3578
37893578
37903579 A timestamp in RFC 3339 format
37913580
3581 format: date-time
3582
37923583 - `created_at: string`
37933584
37943585 A timestamp in RFC 3339 format
37953586
3587 format: date-time
3588
37963589 - `description: string or null`
37973590
37983591 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
from line 3594
38013594
38023595 - `type: "url"`
38033596
3804 - `"url"`
3805
38063597 - `url: string`
38073598
38083599 - `metadata: map[string]`
from line 3672
38813672
38823673 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
38833674
3884 - `BetaManagedAgentsEffortLow object { type }`
3675 - `BetaManagedAgentsEffortLow object`
38853676
38863677 Low effort. Favors latency over reasoning depth.
38873678
38883679 - `type: "low"`
38893680
3890 - `"low"`
3891
3892 - `BetaManagedAgentsEffortMedium object { type }`
3681 - `BetaManagedAgentsEffortMedium object`
38933682
38943683 Medium effort. Balances latency and reasoning depth.
38953684
38963685 - `type: "medium"`
38973686
3898 - `"medium"`
3899
3900 - `BetaManagedAgentsEffortHigh object { type }`
3687 - `BetaManagedAgentsEffortHigh object`
39013688
39023689 High effort. Favors reasoning depth.
39033690
39043691 - `type: "high"`
39053692
3906 - `"high"`
3907
3908 - `BetaManagedAgentsEffortXhigh object { type }`
3693 - `BetaManagedAgentsEffortXhigh object`
39093694
39103695 Extra-high effort. Not all models accept this level.
39113696
39123697 - `type: "xhigh"`
39133698
3914 - `"xhigh"`
3915
3916 - `BetaManagedAgentsEffortMax object { type }`
3699 - `BetaManagedAgentsEffortMax object`
39173700
39183701 Maximum effort. Favors reasoning depth over latency.
39193702
39203703 - `type: "max"`
39213704
3922 - `"max"`
3923
39243705 - `inference_geo: optional string`
39253706
39263707 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 3722
39413722
39423723 Agents the coordinator may spawn as session threads, each resolved to a specific version.
39433724
3944 - `BetaManagedAgentsAgentReference object { id, type, version }`
3725 - `BetaManagedAgentsAgentReference object`
39453726
39463727 A resolved agent reference with a concrete version.
39473728
from line 3730
39493730
39503731 - `type: "agent"`
39513732
3952 - `"agent"`
3953
39543733 - `version: number`
39553734
3956 - `BetaManagedAgentsAdvisor object { model, type }`
3735 format: int32
3736
3737 - `BetaManagedAgentsAdvisor object`
39573738
39583739 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
39593740
from line 3744
39633744
39643745 - `type: "advisor"`
39653746
3966 - `"advisor"`
3967
39683747 - `type: "coordinator"`
39693748
3970 - `"coordinator"`
3971
39723749 - `name: string`
39733750
39743751 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
39753752
3976 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
3753 - `BetaManagedAgentsAnthropicSkill object`
39773754
39783755 A resolved Anthropic-managed skill.
39793756
from line 3758
39813758
39823759 - `type: "anthropic"`
39833760
3984 - `"anthropic"`
3985
39863761 - `version: string`
39873762
3988 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
3763 - `BetaManagedAgentsCustomSkill object`
39893764
39903765 A resolved user-created custom skill.
39913766
from line 3768
39933768
39943769 - `type: "custom"`
39953770
3996 - `"custom"`
3997
39983771 - `version: string`
39993772
40003773 - `system: string or null`
40013774
40023775 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
40033776
4004 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
3777 - `BetaManagedAgentsAgentToolset20260401 object`
40053778
40063779 - `configs: array of BetaManagedAgentsAgentToolConfig`
40073780
4008 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
3781 - `BetaManagedAgentsBashToolConfig object`
40093782
40103783 Configuration for the bash tool.
40113784
from line 3786
40133786
40143787 - `name: "bash"`
40153788
4016 - `"bash"`
4017
40183789 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
40193790
40203791 Permission policy for tool execution.
40213792
4022 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
3793 - `BetaManagedAgentsAlwaysAllowPolicy object`
40233794
40243795 Tool calls are automatically approved without user confirmation.
40253796
40263797 - `type: "always_allow"`
40273798
4028 - `"always_allow"`
4029
4030 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
3799 - `BetaManagedAgentsAlwaysAskPolicy object`
40313800
40323801 Tool calls require user confirmation before execution.
40333802
40343803 - `type: "always_ask"`
40353804
4036 - `"always_ask"`
4037
40383805 - `type: "bash"`
40393806
4040 - `"bash"`
4041
4042 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
3807 - `BetaManagedAgentsEditToolConfig object`
40433808
40443809 Configuration for the edit tool.
40453810
from line 3812
40473812
40483813 - `name: "edit"`
40493814
4050 - `"edit"`
4051
40523815 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
40533816
40543817 Permission policy for tool execution.
40553818
4056 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
3819 - `BetaManagedAgentsAlwaysAllowPolicy object`
40573820
40583821 Tool calls are automatically approved without user confirmation.
40593822
4060 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
3823 - `BetaManagedAgentsAlwaysAskPolicy object`
40613824
40623825 Tool calls require user confirmation before execution.
40633826
40643827 - `type: "edit"`
40653828
4066 - `"edit"`
4067
4068 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
3829 - `BetaManagedAgentsReadToolConfig object`
40693830
40703831 Configuration for the read tool.
40713832
from line 3834
40733834
40743835 - `name: "read"`
40753836
4076 - `"read"`
4077
40783837 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
40793838
40803839 Permission policy for tool execution.
40813840
4082 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
3841 - `BetaManagedAgentsAlwaysAllowPolicy object`
40833842
40843843 Tool calls are automatically approved without user confirmation.
40853844
4086 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
3845 - `BetaManagedAgentsAlwaysAskPolicy object`
40873846
40883847 Tool calls require user confirmation before execution.
40893848
40903849 - `type: "read"`
40913850
4092 - `"read"`
4093
4094 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
3851 - `BetaManagedAgentsWriteToolConfig object`
40953852
40963853 Configuration for the write tool.
40973854
from line 3856
40993856
41003857 - `name: "write"`
41013858
4102 - `"write"`
4103
41043859 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
41053860
41063861 Permission policy for tool execution.
41073862
4108 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
3863 - `BetaManagedAgentsAlwaysAllowPolicy object`
41093864
41103865 Tool calls are automatically approved without user confirmation.
41113866
4112 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
3867 - `BetaManagedAgentsAlwaysAskPolicy object`
41133868
41143869 Tool calls require user confirmation before execution.
41153870
41163871 - `type: "write"`
41173872
4118 - `"write"`
4119
4120 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
3873 - `BetaManagedAgentsGlobToolConfig object`
41213874
41223875 Configuration for the glob tool.
41233876
from line 3878
41253878
41263879 - `name: "glob"`
41273880
4128 - `"glob"`
4129
41303881 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
41313882
41323883 Permission policy for tool execution.
41333884
4134 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
3885 - `BetaManagedAgentsAlwaysAllowPolicy object`
41353886
41363887 Tool calls are automatically approved without user confirmation.
41373888
4138 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
3889 - `BetaManagedAgentsAlwaysAskPolicy object`
41393890
41403891 Tool calls require user confirmation before execution.
41413892
41423893 - `type: "glob"`
41433894
4144 - `"glob"`
4145
4146 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
3895 - `BetaManagedAgentsGrepToolConfig object`
41473896
41483897 Configuration for the grep tool.
41493898
from line 3900
41513900
41523901 - `name: "grep"`
41533902
4154 - `"grep"`
4155
41563903 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
41573904
41583905 Permission policy for tool execution.
41593906
4160 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
3907 - `BetaManagedAgentsAlwaysAllowPolicy object`
41613908
41623909 Tool calls are automatically approved without user confirmation.
41633910
4164 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
3911 - `BetaManagedAgentsAlwaysAskPolicy object`
41653912
41663913 Tool calls require user confirmation before execution.
41673914
41683915 - `type: "grep"`
41693916
4170 - `"grep"`
4171
4172 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
3917 - `BetaManagedAgentsWebFetchToolConfig object`
41733918
41743919 Configuration for the web_fetch tool.
41753920
from line 3922
41773922
41783923 - `name: "web_fetch"`
41793924
4180 - `"web_fetch"`
4181
41823925 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
41833926
41843927 Permission policy for tool execution.
41853928
4186 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
3929 - `BetaManagedAgentsAlwaysAllowPolicy object`
41873930
41883931 Tool calls are automatically approved without user confirmation.
41893932
4190 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
3933 - `BetaManagedAgentsAlwaysAskPolicy object`
41913934
41923935 Tool calls require user confirmation before execution.
41933936
41943937 - `type: "web_fetch"`
41953938
4196 - `"web_fetch"`
4197
41983939 - `allowed_domains: optional array of string`
41993940
42003941 - `blocked_domains: optional array of string`
42013942
42023943 - `max_content_tokens: optional number or null`
42033944
4204 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
3945 format: int32
3946
3947 - `BetaManagedAgentsWebSearchToolConfig object`
42053948
42063949 Configuration for the web_search tool.
42073950
from line 3952
42093952
42103953 - `name: "web_search"`
42113954
4212 - `"web_search"`
4213
42143955 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
42153956
42163957 Permission policy for tool execution.
42173958
4218 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
3959 - `BetaManagedAgentsAlwaysAllowPolicy object`
42193960
42203961 Tool calls are automatically approved without user confirmation.
42213962
4222 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
3963 - `BetaManagedAgentsAlwaysAskPolicy object`
42233964
42243965 Tool calls require user confirmation before execution.
42253966
42263967 - `type: "web_search"`
42273968
4228 - `"web_search"`
4229
42303969 - `allowed_domains: optional array of string`
42313970
42323971 - `blocked_domains: optional array of string`
from line 3978
42393978
42403979 Location precision. Only "approximate" is supported.
42413980
4242 - `"approximate"`
4243
42443981 - `city: optional string or null`
42453982
42463983 City name.
42473984
3985 minLength: 1, maxLength: 255
3986
42483987 - `country: optional string or null`
42493988
42503989 Two-letter ISO 3166-1 country code, uppercase.
from line 3992
42533992
42543993 Region or state name.
42553994
3995 minLength: 1, maxLength: 255
3996
42563997 - `timezone: optional string or null`
42573998
42583999 IANA timezone identifier, e.g. "America/Los_Angeles".
42594000
4001 minLength: 1, maxLength: 255
4002
42604003 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
42614004
42624005 Resolved default configuration for agent tools.
from line 4010
42674010
42684011 Permission policy for tool execution.
42694012
4270 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4013 - `BetaManagedAgentsAlwaysAllowPolicy object`
42714014
42724015 Tool calls are automatically approved without user confirmation.
42734016
4274 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4017 - `BetaManagedAgentsAlwaysAskPolicy object`
42754018
42764019 Tool calls require user confirmation before execution.
42774020
42784021 - `type: "agent_toolset_20260401"`
42794022
4280 - `"agent_toolset_20260401"`
4281
4282 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
4023 - `BetaManagedAgentsMCPToolset object`
42834024
42844025 - `configs: array of BetaManagedAgentsMCPToolConfig`
42854026
from line 4032
42914032
42924033 Permission policy for tool execution.
42934034
4294 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4035 - `BetaManagedAgentsAlwaysAllowPolicy object`
42954036
42964037 Tool calls are automatically approved without user confirmation.
42974038
4298 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4039 - `BetaManagedAgentsAlwaysAskPolicy object`
42994040
43004041 Tool calls require user confirmation before execution.
43014042
from line 4050
43094050
43104051 Permission policy for tool execution.
43114052
4312 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4053 - `BetaManagedAgentsAlwaysAllowPolicy object`
43134054
43144055 Tool calls are automatically approved without user confirmation.
43154056
4316 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4057 - `BetaManagedAgentsAlwaysAskPolicy object`
43174058
43184059 Tool calls require user confirmation before execution.
43194060
from line 4062
43214062
43224063 - `type: "mcp_toolset"`
43234064
4324 - `"mcp_toolset"`
4325
4326 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
4065 - `BetaManagedAgentsCustomTool object`
43274066
43284067 A custom tool as returned in API responses.
43294068
from line 4074
43354074
43364075 - `type: "object"`
43374076
4338 - `"object"`
4339
43404077 - `properties: optional map[unknown] or null`
43414078
43424079 - `required: optional array of string or null`
from line 4082
43454082
43464083 - `type: "custom"`
43474084
4348 - `"custom"`
4349
43504085 - `type: "agent"`
43514086
4352 - `"agent"`
4353
43544087 - `updated_at: string`
43554088
43564089 A timestamp in RFC 3339 format
43574090
4091 format: date-time
4092
43584093 - `version: number`
43594094
43604095 The agent's current version. Starts at 1 and increments when the agent is modified.
43614096
4097 format: int32
4098
43624099### Example
43634100
4364```http
4101```bash
43654102curl https://api.anthropic.com/v1/agents/$AGENT_ID \
43664103 -H 'Content-Type: application/json' \
43674104 -H 'anthropic-version: 2023-06-01' \
from line 4111
43744111 }'
43754112```
43764113
4377#### Response
4114#### Response (200)
43784115
43794116```json
43804117{
from line 4190
44534190
44544191## Archive Agent
44554192
4456**post** `/v1/agents/{agent_id}/archive`
4193**POST** `/v1/agents/{agent_id}/archive`
44574194
44584195Archive Agent
44594196
4460### Path Parameters
4197### Path parameters
44614198
44624199- `agent_id: string`
44634200
4464### Header Parameters
4201### Headers
44654202
44664203- `"anthropic-beta": optional array of AnthropicBeta`
44674204
from line 4278
45414278
45424279### Returns
45434280
4544- `BetaManagedAgentsAgent object { id, archived_at, created_at, 12 more }`
4281- `BetaManagedAgentsAgent object`
45454282
45464283 A Managed Agents `agent`.
45474284
from line 4288
45514288
45524289 A timestamp in RFC 3339 format
45534290
4291 format: date-time
4292
45544293 - `created_at: string`
45554294
45564295 A timestamp in RFC 3339 format
45574296
4297 format: date-time
4298
45584299 - `description: string or null`
45594300
45604301 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
from line 4304
45634304
45644305 - `type: "url"`
45654306
4566 - `"url"`
4567
45684307 - `url: string`
45694308
45704309 - `metadata: map[string]`
from line 4382
46434382
46444383 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
46454384
4646 - `BetaManagedAgentsEffortLow object { type }`
4385 - `BetaManagedAgentsEffortLow object`
46474386
46484387 Low effort. Favors latency over reasoning depth.
46494388
46504389 - `type: "low"`
46514390
4652 - `"low"`
4653
4654 - `BetaManagedAgentsEffortMedium object { type }`
4391 - `BetaManagedAgentsEffortMedium object`
46554392
46564393 Medium effort. Balances latency and reasoning depth.
46574394
46584395 - `type: "medium"`
46594396
4660 - `"medium"`
4661
4662 - `BetaManagedAgentsEffortHigh object { type }`
4397 - `BetaManagedAgentsEffortHigh object`
46634398
46644399 High effort. Favors reasoning depth.
46654400
46664401 - `type: "high"`
46674402
4668 - `"high"`
4669
4670 - `BetaManagedAgentsEffortXhigh object { type }`
4403 - `BetaManagedAgentsEffortXhigh object`
46714404
46724405 Extra-high effort. Not all models accept this level.
46734406
46744407 - `type: "xhigh"`
46754408
4676 - `"xhigh"`
4677
4678 - `BetaManagedAgentsEffortMax object { type }`
4409 - `BetaManagedAgentsEffortMax object`
46794410
46804411 Maximum effort. Favors reasoning depth over latency.
46814412
46824413 - `type: "max"`
46834414
4684 - `"max"`
4685
46864415 - `inference_geo: optional string`
46874416
46884417 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 4432
47034432
47044433 Agents the coordinator may spawn as session threads, each resolved to a specific version.
47054434
4706 - `BetaManagedAgentsAgentReference object { id, type, version }`
4435 - `BetaManagedAgentsAgentReference object`
47074436
47084437 A resolved agent reference with a concrete version.
47094438
from line 4440
47114440
47124441 - `type: "agent"`
47134442
4714 - `"agent"`
4715
47164443 - `version: number`
47174444
4718 - `BetaManagedAgentsAdvisor object { model, type }`
4445 format: int32
4446
4447 - `BetaManagedAgentsAdvisor object`
47194448
47204449 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
47214450
from line 4454
47254454
47264455 - `type: "advisor"`
47274456
4728 - `"advisor"`
4729
47304457 - `type: "coordinator"`
47314458
4732 - `"coordinator"`
4733
47344459 - `name: string`
47354460
47364461 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
47374462
4738 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
4463 - `BetaManagedAgentsAnthropicSkill object`
47394464
47404465 A resolved Anthropic-managed skill.
47414466
from line 4468
47434468
47444469 - `type: "anthropic"`
47454470
4746 - `"anthropic"`
4747
47484471 - `version: string`
47494472
4750 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
4473 - `BetaManagedAgentsCustomSkill object`
47514474
47524475 A resolved user-created custom skill.
47534476
from line 4478
47554478
47564479 - `type: "custom"`
47574480
4758 - `"custom"`
4759
47604481 - `version: string`
47614482
47624483 - `system: string or null`
47634484
47644485 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
47654486
4766 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
4487 - `BetaManagedAgentsAgentToolset20260401 object`
47674488
47684489 - `configs: array of BetaManagedAgentsAgentToolConfig`
47694490
4770 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
4491 - `BetaManagedAgentsBashToolConfig object`
47714492
47724493 Configuration for the bash tool.
47734494
from line 4496
47754496
47764497 - `name: "bash"`
47774498
4778 - `"bash"`
4779
47804499 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
47814500
47824501 Permission policy for tool execution.
47834502
4784 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4503 - `BetaManagedAgentsAlwaysAllowPolicy object`
47854504
47864505 Tool calls are automatically approved without user confirmation.
47874506
47884507 - `type: "always_allow"`
47894508
4790 - `"always_allow"`
4791
4792 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4509 - `BetaManagedAgentsAlwaysAskPolicy object`
47934510
47944511 Tool calls require user confirmation before execution.
47954512
47964513 - `type: "always_ask"`
47974514
4798 - `"always_ask"`
4799
48004515 - `type: "bash"`
48014516
4802 - `"bash"`
4803
4804 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
4517 - `BetaManagedAgentsEditToolConfig object`
48054518
48064519 Configuration for the edit tool.
48074520
from line 4522
48094522
48104523 - `name: "edit"`
48114524
4812 - `"edit"`
4813
48144525 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
48154526
48164527 Permission policy for tool execution.
48174528
4818 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4529 - `BetaManagedAgentsAlwaysAllowPolicy object`
48194530
48204531 Tool calls are automatically approved without user confirmation.
48214532
4822 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4533 - `BetaManagedAgentsAlwaysAskPolicy object`
48234534
48244535 Tool calls require user confirmation before execution.
48254536
48264537 - `type: "edit"`
48274538
4828 - `"edit"`
4829
4830 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
4539 - `BetaManagedAgentsReadToolConfig object`
48314540
48324541 Configuration for the read tool.
48334542
from line 4544
48354544
48364545 - `name: "read"`
48374546
4838 - `"read"`
4839
48404547 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
48414548
48424549 Permission policy for tool execution.
48434550
4844 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4551 - `BetaManagedAgentsAlwaysAllowPolicy object`
48454552
48464553 Tool calls are automatically approved without user confirmation.
48474554
4848 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4555 - `BetaManagedAgentsAlwaysAskPolicy object`
48494556
48504557 Tool calls require user confirmation before execution.
48514558
48524559 - `type: "read"`
48534560
4854 - `"read"`
4855
4856 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
4561 - `BetaManagedAgentsWriteToolConfig object`
48574562
48584563 Configuration for the write tool.
48594564
from line 4566
48614566
48624567 - `name: "write"`
48634568
4864 - `"write"`
4865
48664569 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
48674570
48684571 Permission policy for tool execution.
48694572
4870 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4573 - `BetaManagedAgentsAlwaysAllowPolicy object`
48714574
48724575 Tool calls are automatically approved without user confirmation.
48734576
4874 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4577 - `BetaManagedAgentsAlwaysAskPolicy object`
48754578
48764579 Tool calls require user confirmation before execution.
48774580
48784581 - `type: "write"`
48794582
4880 - `"write"`
4881
4882 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
4583 - `BetaManagedAgentsGlobToolConfig object`
48834584
48844585 Configuration for the glob tool.
48854586
from line 4588
48874588
48884589 - `name: "glob"`
48894590
4890 - `"glob"`
4891
48924591 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
48934592
48944593 Permission policy for tool execution.
48954594
4896 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4595 - `BetaManagedAgentsAlwaysAllowPolicy object`
48974596
48984597 Tool calls are automatically approved without user confirmation.
48994598
4900 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4599 - `BetaManagedAgentsAlwaysAskPolicy object`
49014600
49024601 Tool calls require user confirmation before execution.
49034602
49044603 - `type: "glob"`
49054604
4906 - `"glob"`
4907
4908 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
4605 - `BetaManagedAgentsGrepToolConfig object`
49094606
49104607 Configuration for the grep tool.
49114608
from line 4610
49134610
49144611 - `name: "grep"`
49154612
4916 - `"grep"`
4917
49184613 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
49194614
49204615 Permission policy for tool execution.
49214616
4922 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4617 - `BetaManagedAgentsAlwaysAllowPolicy object`
49234618
49244619 Tool calls are automatically approved without user confirmation.
49254620
4926 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4621 - `BetaManagedAgentsAlwaysAskPolicy object`
49274622
49284623 Tool calls require user confirmation before execution.
49294624
49304625 - `type: "grep"`
49314626
4932 - `"grep"`
4933
4934 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
4627 - `BetaManagedAgentsWebFetchToolConfig object`
49354628
49364629 Configuration for the web_fetch tool.
49374630
from line 4632
49394632
49404633 - `name: "web_fetch"`
49414634
4942 - `"web_fetch"`
4943
49444635 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
49454636
49464637 Permission policy for tool execution.
49474638
4948 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4639 - `BetaManagedAgentsAlwaysAllowPolicy object`
49494640
49504641 Tool calls are automatically approved without user confirmation.
49514642
4952 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4643 - `BetaManagedAgentsAlwaysAskPolicy object`
49534644
49544645 Tool calls require user confirmation before execution.
49554646
49564647 - `type: "web_fetch"`
49574648
4958 - `"web_fetch"`
4959
49604649 - `allowed_domains: optional array of string`
49614650
49624651 - `blocked_domains: optional array of string`
49634652
49644653 - `max_content_tokens: optional number or null`
49654654
4966 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
4655 format: int32
4656
4657 - `BetaManagedAgentsWebSearchToolConfig object`
49674658
49684659 Configuration for the web_search tool.
49694660
from line 4662
49714662
49724663 - `name: "web_search"`
49734664
4974 - `"web_search"`
4975
49764665 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
49774666
49784667 Permission policy for tool execution.
49794668
4980 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4669 - `BetaManagedAgentsAlwaysAllowPolicy object`
49814670
49824671 Tool calls are automatically approved without user confirmation.
49834672
4984 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4673 - `BetaManagedAgentsAlwaysAskPolicy object`
49854674
49864675 Tool calls require user confirmation before execution.
49874676
49884677 - `type: "web_search"`
49894678
4990 - `"web_search"`
4991
49924679 - `allowed_domains: optional array of string`
49934680
49944681 - `blocked_domains: optional array of string`
from line 4688
50014688
50024689 Location precision. Only "approximate" is supported.
50034690
5004 - `"approximate"`
5005
50064691 - `city: optional string or null`
50074692
50084693 City name.
50094694
4695 minLength: 1, maxLength: 255
4696
50104697 - `country: optional string or null`
50114698
50124699 Two-letter ISO 3166-1 country code, uppercase.
from line 4702
50154702
50164703 Region or state name.
50174704
4705 minLength: 1, maxLength: 255
4706
50184707 - `timezone: optional string or null`
50194708
50204709 IANA timezone identifier, e.g. "America/Los_Angeles".
50214710
4711 minLength: 1, maxLength: 255
4712
50224713 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
50234714
50244715 Resolved default configuration for agent tools.
from line 4720
50294720
50304721 Permission policy for tool execution.
50314722
5032 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4723 - `BetaManagedAgentsAlwaysAllowPolicy object`
50334724
50344725 Tool calls are automatically approved without user confirmation.
50354726
5036 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4727 - `BetaManagedAgentsAlwaysAskPolicy object`
50374728
50384729 Tool calls require user confirmation before execution.
50394730
50404731 - `type: "agent_toolset_20260401"`
50414732
5042 - `"agent_toolset_20260401"`
5043
5044 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
4733 - `BetaManagedAgentsMCPToolset object`
50454734
50464735 - `configs: array of BetaManagedAgentsMCPToolConfig`
50474736
from line 4742
50534742
50544743 Permission policy for tool execution.
50554744
5056 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4745 - `BetaManagedAgentsAlwaysAllowPolicy object`
50574746
50584747 Tool calls are automatically approved without user confirmation.
50594748
5060 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4749 - `BetaManagedAgentsAlwaysAskPolicy object`
50614750
50624751 Tool calls require user confirmation before execution.
50634752
from line 4760
50714760
50724761 Permission policy for tool execution.
50734762
5074 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4763 - `BetaManagedAgentsAlwaysAllowPolicy object`
50754764
50764765 Tool calls are automatically approved without user confirmation.
50774766
5078 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4767 - `BetaManagedAgentsAlwaysAskPolicy object`
50794768
50804769 Tool calls require user confirmation before execution.
50814770
from line 4772
50834772
50844773 - `type: "mcp_toolset"`
50854774
5086 - `"mcp_toolset"`
5087
5088 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
4775 - `BetaManagedAgentsCustomTool object`
50894776
50904777 A custom tool as returned in API responses.
50914778
from line 4784
50974784
50984785 - `type: "object"`
50994786
5100 - `"object"`
5101
51024787 - `properties: optional map[unknown] or null`
51034788
51044789 - `required: optional array of string or null`
from line 4792
51074792
51084793 - `type: "custom"`
51094794
5110 - `"custom"`
5111
51124795 - `type: "agent"`
51134796
5114 - `"agent"`
5115
51164797 - `updated_at: string`
51174798
51184799 A timestamp in RFC 3339 format
51194800
4801 format: date-time
4802
51204803 - `version: number`
51214804
51224805 The agent's current version. Starts at 1 and increments when the agent is modified.
51234806
4807 format: int32
4808
51244809### Example
51254810
5126```http
4811```bash
51274812curl https://api.anthropic.com/v1/agents/$AGENT_ID/archive \
51284813 -X POST \
51294814 -H 'anthropic-version: 2023-06-01' \
from line 4816
51314816 -H "X-Api-Key: $ANTHROPIC_API_KEY"
51324817```
51334818
5134#### Response
4819#### Response (200)
51354820
51364821```json
51374822{
from line 4893
52084893}
52094894```
52104895
5211## Domain Types
4896## Domain types
52124897
52134898### Beta Managed Agents Advisor
52144899
5215- `BetaManagedAgentsAdvisor object { model, type }`
4900- `BetaManagedAgentsAdvisor object`
52164901
52174902 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
52184903
from line 4907
52224907
52234908 - `type: "advisor"`
52244909
5225 - `"advisor"`
5226
52274910### Beta Managed Agents Agent
52284911
5229- `BetaManagedAgentsAgent object { id, archived_at, created_at, 12 more }`
4912- `BetaManagedAgentsAgent object`
52304913
52314914 A Managed Agents `agent`.
52324915
from line 4919
52364919
52374920 A timestamp in RFC 3339 format
52384921
4922 format: date-time
4923
52394924 - `created_at: string`
52404925
52414926 A timestamp in RFC 3339 format
52424927
4928 format: date-time
4929
52434930 - `description: string or null`
52444931
52454932 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
from line 4935
52484935
52494936 - `type: "url"`
52504937
5251 - `"url"`
5252
52534938 - `url: string`
52544939
52554940 - `metadata: map[string]`
from line 5013
53285013
53295014 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
53305015
5331 - `BetaManagedAgentsEffortLow object { type }`
5016 - `BetaManagedAgentsEffortLow object`
53325017
53335018 Low effort. Favors latency over reasoning depth.
53345019
53355020 - `type: "low"`
53365021
5337 - `"low"`
5338
5339 - `BetaManagedAgentsEffortMedium object { type }`
5022 - `BetaManagedAgentsEffortMedium object`
53405023
53415024 Medium effort. Balances latency and reasoning depth.
53425025
53435026 - `type: "medium"`
53445027
5345 - `"medium"`
5346
5347 - `BetaManagedAgentsEffortHigh object { type }`
5028 - `BetaManagedAgentsEffortHigh object`
53485029
53495030 High effort. Favors reasoning depth.
53505031
53515032 - `type: "high"`
53525033
5353 - `"high"`
5354
5355 - `BetaManagedAgentsEffortXhigh object { type }`
5034 - `BetaManagedAgentsEffortXhigh object`
53565035
53575036 Extra-high effort. Not all models accept this level.
53585037
53595038 - `type: "xhigh"`
53605039
5361 - `"xhigh"`
5362
5363 - `BetaManagedAgentsEffortMax object { type }`
5040 - `BetaManagedAgentsEffortMax object`
53645041
53655042 Maximum effort. Favors reasoning depth over latency.
53665043
53675044 - `type: "max"`
53685045
5369 - `"max"`
5370
53715046 - `inference_geo: optional string`
53725047
53735048 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 5063
53885063
53895064 Agents the coordinator may spawn as session threads, each resolved to a specific version.
53905065
5391 - `BetaManagedAgentsAgentReference object { id, type, version }`
5066 - `BetaManagedAgentsAgentReference object`
53925067
53935068 A resolved agent reference with a concrete version.
53945069
from line 5071
53965071
53975072 - `type: "agent"`
53985073
5399 - `"agent"`
5400
54015074 - `version: number`
54025075
5403 - `BetaManagedAgentsAdvisor object { model, type }`
5076 format: int32
5077
5078 - `BetaManagedAgentsAdvisor object`
54045079
54055080 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
54065081
from line 5085
54105085
54115086 - `type: "advisor"`
54125087
5413 - `"advisor"`
5414
54155088 - `type: "coordinator"`
54165089
5417 - `"coordinator"`
5418
54195090 - `name: string`
54205091
54215092 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
54225093
5423 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
5094 - `BetaManagedAgentsAnthropicSkill object`
54245095
54255096 A resolved Anthropic-managed skill.
54265097
from line 5099
54285099
54295100 - `type: "anthropic"`
54305101
5431 - `"anthropic"`
5432
54335102 - `version: string`
54345103
5435 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
5104 - `BetaManagedAgentsCustomSkill object`
54365105
54375106 A resolved user-created custom skill.
54385107
from line 5109
54405109
54415110 - `type: "custom"`
54425111
5443 - `"custom"`
5444
54455112 - `version: string`
54465113
54475114 - `system: string or null`
54485115
54495116 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
54505117
5451 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
5118 - `BetaManagedAgentsAgentToolset20260401 object`
54525119
54535120 - `configs: array of BetaManagedAgentsAgentToolConfig`
54545121
5455 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
5122 - `BetaManagedAgentsBashToolConfig object`
54565123
54575124 Configuration for the bash tool.
54585125
from line 5127
54605127
54615128 - `name: "bash"`
54625129
5463 - `"bash"`
5464
54655130 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
54665131
54675132 Permission policy for tool execution.
54685133
5469 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5134 - `BetaManagedAgentsAlwaysAllowPolicy object`
54705135
54715136 Tool calls are automatically approved without user confirmation.
54725137
54735138 - `type: "always_allow"`
54745139
5475 - `"always_allow"`
5476
5477 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5140 - `BetaManagedAgentsAlwaysAskPolicy object`
54785141
54795142 Tool calls require user confirmation before execution.
54805143
54815144 - `type: "always_ask"`
54825145
5483 - `"always_ask"`
5484
54855146 - `type: "bash"`
54865147
5487 - `"bash"`
5488
5489 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
5148 - `BetaManagedAgentsEditToolConfig object`
54905149
54915150 Configuration for the edit tool.
54925151
from line 5153
54945153
54955154 - `name: "edit"`
54965155
5497 - `"edit"`
5498
54995156 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
55005157
55015158 Permission policy for tool execution.
55025159
5503 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5160 - `BetaManagedAgentsAlwaysAllowPolicy object`
55045161
55055162 Tool calls are automatically approved without user confirmation.
55065163
5507 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5164 - `BetaManagedAgentsAlwaysAskPolicy object`
55085165
55095166 Tool calls require user confirmation before execution.
55105167
55115168 - `type: "edit"`
55125169
5513 - `"edit"`
5514
5515 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
5170 - `BetaManagedAgentsReadToolConfig object`
55165171
55175172 Configuration for the read tool.
55185173
from line 5175
55205175
55215176 - `name: "read"`
55225177
5523 - `"read"`
5524
55255178 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
55265179
55275180 Permission policy for tool execution.
55285181
5529 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5182 - `BetaManagedAgentsAlwaysAllowPolicy object`
55305183
55315184 Tool calls are automatically approved without user confirmation.
55325185
5533 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5186 - `BetaManagedAgentsAlwaysAskPolicy object`
55345187
55355188 Tool calls require user confirmation before execution.
55365189
55375190 - `type: "read"`
55385191
5539 - `"read"`
5540
5541 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
5192 - `BetaManagedAgentsWriteToolConfig object`
55425193
55435194 Configuration for the write tool.
55445195
from line 5197
55465197
55475198 - `name: "write"`
55485199
5549 - `"write"`
5550
55515200 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
55525201
55535202 Permission policy for tool execution.
55545203
5555 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5204 - `BetaManagedAgentsAlwaysAllowPolicy object`
55565205
55575206 Tool calls are automatically approved without user confirmation.
55585207
5559 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5208 - `BetaManagedAgentsAlwaysAskPolicy object`
55605209
55615210 Tool calls require user confirmation before execution.
55625211
55635212 - `type: "write"`
55645213
5565 - `"write"`
5566
5567 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
5214 - `BetaManagedAgentsGlobToolConfig object`
55685215
55695216 Configuration for the glob tool.
55705217
from line 5219
55725219
55735220 - `name: "glob"`
55745221
5575 - `"glob"`
5576
55775222 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
55785223
55795224 Permission policy for tool execution.
55805225
5581 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5226 - `BetaManagedAgentsAlwaysAllowPolicy object`
55825227
55835228 Tool calls are automatically approved without user confirmation.
55845229
5585 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5230 - `BetaManagedAgentsAlwaysAskPolicy object`
55865231
55875232 Tool calls require user confirmation before execution.
55885233
55895234 - `type: "glob"`
55905235
5591 - `"glob"`
5592
5593 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
5236 - `BetaManagedAgentsGrepToolConfig object`
55945237
55955238 Configuration for the grep tool.
55965239
from line 5241
55985241
55995242 - `name: "grep"`
56005243
5601 - `"grep"`
5602
56035244 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
56045245
56055246 Permission policy for tool execution.
56065247
5607 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5248 - `BetaManagedAgentsAlwaysAllowPolicy object`
56085249
56095250 Tool calls are automatically approved without user confirmation.
56105251
5611 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5252 - `BetaManagedAgentsAlwaysAskPolicy object`
56125253
56135254 Tool calls require user confirmation before execution.
56145255
56155256 - `type: "grep"`
56165257
5617 - `"grep"`
5618
5619 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
5258 - `BetaManagedAgentsWebFetchToolConfig object`
56205259
56215260 Configuration for the web_fetch tool.
56225261
from line 5263
56245263
56255264 - `name: "web_fetch"`
56265265
5627 - `"web_fetch"`
5628
56295266 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
56305267
56315268 Permission policy for tool execution.
56325269
5633 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5270 - `BetaManagedAgentsAlwaysAllowPolicy object`
56345271
56355272 Tool calls are automatically approved without user confirmation.
56365273
5637 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5274 - `BetaManagedAgentsAlwaysAskPolicy object`
56385275
56395276 Tool calls require user confirmation before execution.
56405277
56415278 - `type: "web_fetch"`
56425279
5643 - `"web_fetch"`
5644
56455280 - `allowed_domains: optional array of string`
56465281
56475282 - `blocked_domains: optional array of string`
56485283
56495284 - `max_content_tokens: optional number or null`
56505285
5651 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
5286 format: int32
5287
5288 - `BetaManagedAgentsWebSearchToolConfig object`
56525289
56535290 Configuration for the web_search tool.
56545291
from line 5293
56565293
56575294 - `name: "web_search"`
56585295
5659 - `"web_search"`
5660
56615296 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
56625297
56635298 Permission policy for tool execution.
56645299
5665 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5300 - `BetaManagedAgentsAlwaysAllowPolicy object`
56665301
56675302 Tool calls are automatically approved without user confirmation.
56685303
5669 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5304 - `BetaManagedAgentsAlwaysAskPolicy object`
56705305
56715306 Tool calls require user confirmation before execution.
56725307
56735308 - `type: "web_search"`
56745309
5675 - `"web_search"`
5676
56775310 - `allowed_domains: optional array of string`
56785311
56795312 - `blocked_domains: optional array of string`
from line 5319
56865319
56875320 Location precision. Only "approximate" is supported.
56885321
5689 - `"approximate"`
5690
56915322 - `city: optional string or null`
56925323
56935324 City name.
56945325
5326 minLength: 1, maxLength: 255
5327
56955328 - `country: optional string or null`
56965329
56975330 Two-letter ISO 3166-1 country code, uppercase.
from line 5333
57005333
57015334 Region or state name.
57025335
5336 minLength: 1, maxLength: 255
5337
57035338 - `timezone: optional string or null`
57045339
57055340 IANA timezone identifier, e.g. "America/Los_Angeles".
57065341
5342 minLength: 1, maxLength: 255
5343
57075344 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
57085345
57095346 Resolved default configuration for agent tools.
from line 5351
57145351
57155352 Permission policy for tool execution.
57165353
5717 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5354 - `BetaManagedAgentsAlwaysAllowPolicy object`
57185355
57195356 Tool calls are automatically approved without user confirmation.
57205357
5721 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5358 - `BetaManagedAgentsAlwaysAskPolicy object`
57225359
57235360 Tool calls require user confirmation before execution.
57245361
57255362 - `type: "agent_toolset_20260401"`
57265363
5727 - `"agent_toolset_20260401"`
5728
5729 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
5364 - `BetaManagedAgentsMCPToolset object`
57305365
57315366 - `configs: array of BetaManagedAgentsMCPToolConfig`
57325367
from line 5373
57385373
57395374 Permission policy for tool execution.
57405375
5741 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5376 - `BetaManagedAgentsAlwaysAllowPolicy object`
57425377
57435378 Tool calls are automatically approved without user confirmation.
57445379
5745 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5380 - `BetaManagedAgentsAlwaysAskPolicy object`
57465381
57475382 Tool calls require user confirmation before execution.
57485383
from line 5391
57565391
57575392 Permission policy for tool execution.
57585393
5759 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5394 - `BetaManagedAgentsAlwaysAllowPolicy object`
57605395
57615396 Tool calls are automatically approved without user confirmation.
57625397
5763 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5398 - `BetaManagedAgentsAlwaysAskPolicy object`
57645399
57655400 Tool calls require user confirmation before execution.
57665401
from line 5403
57685403
57695404 - `type: "mcp_toolset"`
57705405
5771 - `"mcp_toolset"`
5772
5773 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
5406 - `BetaManagedAgentsCustomTool object`
57745407
57755408 A custom tool as returned in API responses.
57765409
from line 5415
57825415
57835416 - `type: "object"`
57845417
5785 - `"object"`
5786
57875418 - `properties: optional map[unknown] or null`
57885419
57895420 - `required: optional array of string or null`
from line 5423
57925423
57935424 - `type: "custom"`
57945425
5795 - `"custom"`
5796
57975426 - `type: "agent"`
57985427
5799 - `"agent"`
5800
58015428 - `updated_at: string`
58025429
58035430 A timestamp in RFC 3339 format
58045431
5432 format: date-time
5433
58055434 - `version: number`
58065435
58075436 The agent's current version. Starts at 1 and increments when the agent is modified.
58085437
5438 format: int32
5439
58095440### Beta Managed Agents Agent Reference
58105441
5811- `BetaManagedAgentsAgentReference object { id, type, version }`
5442- `BetaManagedAgentsAgentReference object`
58125443
58135444 A resolved agent reference with a concrete version.
58145445
from line 5447
58165447
58175448 - `type: "agent"`
58185449
5819 - `"agent"`
5820
58215450 - `version: number`
58225451
5452 format: int32
5453
58235454### Beta Managed Agents Agent Tool Config
58245455
58255456- `BetaManagedAgentsAgentToolConfig = BetaManagedAgentsBashToolConfig or BetaManagedAgentsEditToolConfig or BetaManagedAgentsReadToolConfig or 5 more`
58265457
58275458 Configuration for a specific agent tool.
58285459
5829 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
5460 - `BetaManagedAgentsBashToolConfig object`
58305461
58315462 Configuration for the bash tool.
58325463
from line 5465
58345465
58355466 - `name: "bash"`
58365467
5837 - `"bash"`
5838
58395468 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
58405469
58415470 Permission policy for tool execution.
58425471
5843 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5472 - `BetaManagedAgentsAlwaysAllowPolicy object`
58445473
58455474 Tool calls are automatically approved without user confirmation.
58465475
58475476 - `type: "always_allow"`
58485477
5849 - `"always_allow"`
5850
5851 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5478 - `BetaManagedAgentsAlwaysAskPolicy object`
58525479
58535480 Tool calls require user confirmation before execution.
58545481
58555482 - `type: "always_ask"`
58565483
5857 - `"always_ask"`
5858
58595484 - `type: "bash"`
58605485
5861 - `"bash"`
5862
5863 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
5486 - `BetaManagedAgentsEditToolConfig object`
58645487
58655488 Configuration for the edit tool.
58665489
from line 5491
58685491
58695492 - `name: "edit"`
58705493
5871 - `"edit"`
5872
58735494 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
58745495
58755496 Permission policy for tool execution.
58765497
5877 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5498 - `BetaManagedAgentsAlwaysAllowPolicy object`
58785499
58795500 Tool calls are automatically approved without user confirmation.
58805501
5881 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5502 - `BetaManagedAgentsAlwaysAskPolicy object`
58825503
58835504 Tool calls require user confirmation before execution.
58845505
58855506 - `type: "edit"`
58865507
5887 - `"edit"`
5888
5889 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
5508 - `BetaManagedAgentsReadToolConfig object`
58905509
58915510 Configuration for the read tool.
58925511
from line 5513
58945513
58955514 - `name: "read"`
58965515
5897 - `"read"`
5898
58995516 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
59005517
59015518 Permission policy for tool execution.
59025519
5903 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5520 - `BetaManagedAgentsAlwaysAllowPolicy object`
59045521
59055522 Tool calls are automatically approved without user confirmation.
59065523
5907 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5524 - `BetaManagedAgentsAlwaysAskPolicy object`
59085525
59095526 Tool calls require user confirmation before execution.
59105527
59115528 - `type: "read"`
59125529
5913 - `"read"`
5914
5915 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
5530 - `BetaManagedAgentsWriteToolConfig object`
59165531
59175532 Configuration for the write tool.
59185533
from line 5535
59205535
59215536 - `name: "write"`
59225537
5923 - `"write"`
5924
59255538 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
59265539
59275540 Permission policy for tool execution.
59285541
5929 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5542 - `BetaManagedAgentsAlwaysAllowPolicy object`
59305543
59315544 Tool calls are automatically approved without user confirmation.
59325545
5933 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5546 - `BetaManagedAgentsAlwaysAskPolicy object`
59345547
59355548 Tool calls require user confirmation before execution.
59365549
59375550 - `type: "write"`
59385551
5939 - `"write"`
5940
5941 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
5552 - `BetaManagedAgentsGlobToolConfig object`
59425553
59435554 Configuration for the glob tool.
59445555
from line 5557
59465557
59475558 - `name: "glob"`
59485559
5949 - `"glob"`
5950
59515560 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
59525561
59535562 Permission policy for tool execution.
59545563
5955 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5564 - `BetaManagedAgentsAlwaysAllowPolicy object`
59565565
59575566 Tool calls are automatically approved without user confirmation.
59585567
5959 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5568 - `BetaManagedAgentsAlwaysAskPolicy object`
59605569
59615570 Tool calls require user confirmation before execution.
59625571
59635572 - `type: "glob"`
59645573
5965 - `"glob"`
5966
5967 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
5574 - `BetaManagedAgentsGrepToolConfig object`
59685575
59695576 Configuration for the grep tool.
59705577
from line 5579
59725579
59735580 - `name: "grep"`
59745581
5975 - `"grep"`
5976
59775582 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
59785583
59795584 Permission policy for tool execution.
59805585
5981 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5586 - `BetaManagedAgentsAlwaysAllowPolicy object`
59825587
59835588 Tool calls are automatically approved without user confirmation.
59845589
5985 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5590 - `BetaManagedAgentsAlwaysAskPolicy object`
59865591
59875592 Tool calls require user confirmation before execution.
59885593
59895594 - `type: "grep"`
59905595
5991 - `"grep"`
5992
5993 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
5596 - `BetaManagedAgentsWebFetchToolConfig object`
59945597
59955598 Configuration for the web_fetch tool.
59965599
from line 5601
59985601
59995602 - `name: "web_fetch"`
60005603
6001 - `"web_fetch"`
6002
60035604 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
60045605
60055606 Permission policy for tool execution.
60065607
6007 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5608 - `BetaManagedAgentsAlwaysAllowPolicy object`
60085609
60095610 Tool calls are automatically approved without user confirmation.
60105611
6011 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5612 - `BetaManagedAgentsAlwaysAskPolicy object`
60125613
60135614 Tool calls require user confirmation before execution.
60145615
60155616 - `type: "web_fetch"`
60165617
6017 - `"web_fetch"`
6018
60195618 - `allowed_domains: optional array of string`
60205619
60215620 - `blocked_domains: optional array of string`
60225621
60235622 - `max_content_tokens: optional number or null`
60245623
6025 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
5624 format: int32
5625
5626 - `BetaManagedAgentsWebSearchToolConfig object`
60265627
60275628 Configuration for the web_search tool.
60285629
from line 5631
60305631
60315632 - `name: "web_search"`
60325633
6033 - `"web_search"`
6034
60355634 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
60365635
60375636 Permission policy for tool execution.
60385637
6039 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5638 - `BetaManagedAgentsAlwaysAllowPolicy object`
60405639
60415640 Tool calls are automatically approved without user confirmation.
60425641
6043 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5642 - `BetaManagedAgentsAlwaysAskPolicy object`
60445643
60455644 Tool calls require user confirmation before execution.
60465645
60475646 - `type: "web_search"`
60485647
6049 - `"web_search"`
6050
60515648 - `allowed_domains: optional array of string`
60525649
60535650 - `blocked_domains: optional array of string`
from line 5657
60605657
60615658 Location precision. Only "approximate" is supported.
60625659
6063 - `"approximate"`
6064
60655660 - `city: optional string or null`
60665661
60675662 City name.
60685663
5664 minLength: 1, maxLength: 255
5665
60695666 - `country: optional string or null`
60705667
60715668 Two-letter ISO 3166-1 country code, uppercase.
from line 5671
60745671
60755672 Region or state name.
60765673
5674 minLength: 1, maxLength: 255
5675
60775676 - `timezone: optional string or null`
60785677
60795678 IANA timezone identifier, e.g. "America/Los_Angeles".
60805679
5680 minLength: 1, maxLength: 255
5681
60815682### Beta Managed Agents Agent Tool Config Params
60825683
60835684- `BetaManagedAgentsAgentToolConfigParams = BetaManagedAgentsBashToolConfigParams or BetaManagedAgentsEditToolConfigParams or BetaManagedAgentsReadToolConfigParams or 5 more`
60845685
60855686 Configuration override for a specific tool within a toolset.
60865687
6087 - `BetaManagedAgentsBashToolConfigParams object { name, enabled, permission_policy, type }`
5688 - `BetaManagedAgentsBashToolConfigParams object`
60885689
60895690 Configuration override for the bash tool.
60905691
from line 5693
60925693
60935694 Must be "bash".
60945695
6095 - `"bash"`
6096
60975696 - `enabled: optional boolean or null`
60985697
60995698 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 5701
61025701
61035702 Permission policy for tool execution.
61045703
6105 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5704 - `BetaManagedAgentsAlwaysAllowPolicy object`
61065705
61075706 Tool calls are automatically approved without user confirmation.
61085707
61095708 - `type: "always_allow"`
61105709
6111 - `"always_allow"`
6112
6113 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5710 - `BetaManagedAgentsAlwaysAskPolicy object`
61145711
61155712 Tool calls require user confirmation before execution.
61165713
61175714 - `type: "always_ask"`
61185715
6119 - `"always_ask"`
6120
61215716 - `type: optional "bash"`
61225717
6123 - `"bash"`
6124
6125 - `BetaManagedAgentsEditToolConfigParams object { name, enabled, permission_policy, type }`
5718 - `BetaManagedAgentsEditToolConfigParams object`
61265719
61275720 Configuration override for the edit tool.
61285721
from line 5723
61305723
61315724 Must be "edit".
61325725
6133 - `"edit"`
6134
61355726 - `enabled: optional boolean or null`
61365727
61375728 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 5731
61405731
61415732 Permission policy for tool execution.
61425733
6143 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5734 - `BetaManagedAgentsAlwaysAllowPolicy object`
61445735
61455736 Tool calls are automatically approved without user confirmation.
61465737
6147 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5738 - `BetaManagedAgentsAlwaysAskPolicy object`
61485739
61495740 Tool calls require user confirmation before execution.
61505741
61515742 - `type: optional "edit"`
61525743
6153 - `"edit"`
6154
6155 - `BetaManagedAgentsReadToolConfigParams object { name, enabled, permission_policy, type }`
5744 - `BetaManagedAgentsReadToolConfigParams object`
61565745
61575746 Configuration override for the read tool.
61585747
from line 5749
61605749
61615750 Must be "read".
61625751
6163 - `"read"`
6164
61655752 - `enabled: optional boolean or null`
61665753
61675754 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 5757
61705757
61715758 Permission policy for tool execution.
61725759
6173 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5760 - `BetaManagedAgentsAlwaysAllowPolicy object`
61745761
61755762 Tool calls are automatically approved without user confirmation.
61765763
6177 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5764 - `BetaManagedAgentsAlwaysAskPolicy object`
61785765
61795766 Tool calls require user confirmation before execution.
61805767
61815768 - `type: optional "read"`
61825769
6183 - `"read"`
6184
6185 - `BetaManagedAgentsWriteToolConfigParams object { name, enabled, permission_policy, type }`
5770 - `BetaManagedAgentsWriteToolConfigParams object`
61865771
61875772 Configuration override for the write tool.
61885773
from line 5775
61905775
61915776 Must be "write".
61925777
6193 - `"write"`
6194
61955778 - `enabled: optional boolean or null`
61965779
61975780 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 5783
62005783
62015784 Permission policy for tool execution.
62025785
6203 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5786 - `BetaManagedAgentsAlwaysAllowPolicy object`
62045787
62055788 Tool calls are automatically approved without user confirmation.
62065789
6207 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5790 - `BetaManagedAgentsAlwaysAskPolicy object`
62085791
62095792 Tool calls require user confirmation before execution.
62105793
62115794 - `type: optional "write"`
62125795
6213 - `"write"`
6214
6215 - `BetaManagedAgentsGlobToolConfigParams object { name, enabled, permission_policy, type }`
5796 - `BetaManagedAgentsGlobToolConfigParams object`
62165797
62175798 Configuration override for the glob tool.
62185799
from line 5801
62205801
62215802 Must be "glob".
62225803
6223 - `"glob"`
6224
62255804 - `enabled: optional boolean or null`
62265805
62275806 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 5809
62305809
62315810 Permission policy for tool execution.
62325811
6233 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5812 - `BetaManagedAgentsAlwaysAllowPolicy object`
62345813
62355814 Tool calls are automatically approved without user confirmation.
62365815
6237 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5816 - `BetaManagedAgentsAlwaysAskPolicy object`
62385817
62395818 Tool calls require user confirmation before execution.
62405819
62415820 - `type: optional "glob"`
62425821
6243 - `"glob"`
6244
6245 - `BetaManagedAgentsGrepToolConfigParams object { name, enabled, permission_policy, type }`
5822 - `BetaManagedAgentsGrepToolConfigParams object`
62465823
62475824 Configuration override for the grep tool.
62485825
from line 5827
62505827
62515828 Must be "grep".
62525829
6253 - `"grep"`
6254
62555830 - `enabled: optional boolean or null`
62565831
62575832 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 5835
62605835
62615836 Permission policy for tool execution.
62625837
6263 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5838 - `BetaManagedAgentsAlwaysAllowPolicy object`
62645839
62655840 Tool calls are automatically approved without user confirmation.
62665841
6267 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5842 - `BetaManagedAgentsAlwaysAskPolicy object`
62685843
62695844 Tool calls require user confirmation before execution.
62705845
62715846 - `type: optional "grep"`
62725847
6273 - `"grep"`
6274
6275 - `BetaManagedAgentsWebFetchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }`
5848 - `BetaManagedAgentsWebFetchToolConfigParams object`
62765849
62775850 Configuration override for the web_fetch tool.
62785851
from line 5853
62805853
62815854 Must be "web_fetch".
62825855
6283 - `"web_fetch"`
6284
62855856 - `allowed_domains: optional array of string`
62865857
62875858 Only fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
from line 5869
62985869
62995870 Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs.
63005871
5872 format: int32
5873
63015874 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
63025875
63035876 Permission policy for tool execution.
63045877
6305 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5878 - `BetaManagedAgentsAlwaysAllowPolicy object`
63065879
63075880 Tool calls are automatically approved without user confirmation.
63085881
6309 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5882 - `BetaManagedAgentsAlwaysAskPolicy object`
63105883
63115884 Tool calls require user confirmation before execution.
63125885
63135886 - `type: optional "web_fetch"`
63145887
6315 - `"web_fetch"`
6316
6317 - `BetaManagedAgentsWebSearchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }`
5888 - `BetaManagedAgentsWebSearchToolConfigParams object`
63185889
63195890 Configuration override for the web_search tool.
63205891
from line 5893
63225893
63235894 Must be "web_search".
63245895
6325 - `"web_search"`
6326
63275896 - `allowed_domains: optional array of string`
63285897
63295898 Only return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
from line 5909
63405909
63415910 Permission policy for tool execution.
63425911
6343 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5912 - `BetaManagedAgentsAlwaysAllowPolicy object`
63445913
63455914 Tool calls are automatically approved without user confirmation.
63465915
6347 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5916 - `BetaManagedAgentsAlwaysAskPolicy object`
63485917
63495918 Tool calls require user confirmation before execution.
63505919
63515920 - `type: optional "web_search"`
63525921
6353 - `"web_search"`
6354
63555922 - `user_location: optional BetaManagedAgentsUserLocation or null`
63565923
63575924 Approximate user location for search result localization.
from line 5927
63605927
63615928 Location precision. Only "approximate" is supported.
63625929
6363 - `"approximate"`
6364
63655930 - `city: optional string or null`
63665931
63675932 City name.
63685933
5934 minLength: 1, maxLength: 255
5935
63695936 - `country: optional string or null`
63705937
63715938 Two-letter ISO 3166-1 country code, uppercase.
from line 5941
63745941
63755942 Region or state name.
63765943
5944 minLength: 1, maxLength: 255
5945
63775946 - `timezone: optional string or null`
63785947
63795948 IANA timezone identifier, e.g. "America/Los_Angeles".
63805949
5950 minLength: 1, maxLength: 255
5951
63815952### Beta Managed Agents Agent Toolset Default Config
63825953
6383- `BetaManagedAgentsAgentToolsetDefaultConfig object { enabled, permission_policy }`
5954- `BetaManagedAgentsAgentToolsetDefaultConfig object`
63845955
63855956 Resolved default configuration for agent tools.
63865957
from line 5961
63905961
63915962 Permission policy for tool execution.
63925963
6393 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5964 - `BetaManagedAgentsAlwaysAllowPolicy object`
63945965
63955966 Tool calls are automatically approved without user confirmation.
63965967
63975968 - `type: "always_allow"`
63985969
6399 - `"always_allow"`
6400
6401 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5970 - `BetaManagedAgentsAlwaysAskPolicy object`
64025971
64035972 Tool calls require user confirmation before execution.
64045973
64055974 - `type: "always_ask"`
64065975
6407 - `"always_ask"`
6408
64095976### Beta Managed Agents Agent Toolset Default Config Params
64105977
6411- `BetaManagedAgentsAgentToolsetDefaultConfigParams object { enabled, permission_policy }`
5978- `BetaManagedAgentsAgentToolsetDefaultConfigParams object`
64125979
64135980 Default configuration for all tools in a toolset.
64145981
from line 5987
64205987
64215988 Permission policy for tool execution.
64225989
6423 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
5990 - `BetaManagedAgentsAlwaysAllowPolicy object`
64245991
64255992 Tool calls are automatically approved without user confirmation.
64265993
64275994 - `type: "always_allow"`
64285995
6429 - `"always_allow"`
6430
6431 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
5996 - `BetaManagedAgentsAlwaysAskPolicy object`
64325997
64335998 Tool calls require user confirmation before execution.
64345999
64356000 - `type: "always_ask"`
64366001
6437 - `"always_ask"`
6438
64396002### Beta Managed Agents Agent Toolset20260401
64406003
6441- `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
6004- `BetaManagedAgentsAgentToolset20260401 object`
64426005
64436006 - `configs: array of BetaManagedAgentsAgentToolConfig`
64446007
6445 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
6008 - `BetaManagedAgentsBashToolConfig object`
64466009
64476010 Configuration for the bash tool.
64486011
from line 6013
64506013
64516014 - `name: "bash"`
64526015
6453 - `"bash"`
6454
64556016 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
64566017
64576018 Permission policy for tool execution.
64586019
6459 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6020 - `BetaManagedAgentsAlwaysAllowPolicy object`
64606021
64616022 Tool calls are automatically approved without user confirmation.
64626023
64636024 - `type: "always_allow"`
64646025
6465 - `"always_allow"`
6466
6467 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6026 - `BetaManagedAgentsAlwaysAskPolicy object`
64686027
64696028 Tool calls require user confirmation before execution.
64706029
64716030 - `type: "always_ask"`
64726031
6473 - `"always_ask"`
6474
64756032 - `type: "bash"`
64766033
6477 - `"bash"`
6478
6479 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
6034 - `BetaManagedAgentsEditToolConfig object`
64806035
64816036 Configuration for the edit tool.
64826037
from line 6039
64846039
64856040 - `name: "edit"`
64866041
6487 - `"edit"`
6488
64896042 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
64906043
64916044 Permission policy for tool execution.
64926045
6493 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6046 - `BetaManagedAgentsAlwaysAllowPolicy object`
64946047
64956048 Tool calls are automatically approved without user confirmation.
64966049
6497 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6050 - `BetaManagedAgentsAlwaysAskPolicy object`
64986051
64996052 Tool calls require user confirmation before execution.
65006053
65016054 - `type: "edit"`
65026055
6503 - `"edit"`
6504
6505 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
6056 - `BetaManagedAgentsReadToolConfig object`
65066057
65076058 Configuration for the read tool.
65086059
from line 6061
65106061
65116062 - `name: "read"`
65126063
6513 - `"read"`
6514
65156064 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
65166065
65176066 Permission policy for tool execution.
65186067
6519 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6068 - `BetaManagedAgentsAlwaysAllowPolicy object`
65206069
65216070 Tool calls are automatically approved without user confirmation.
65226071
6523 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6072 - `BetaManagedAgentsAlwaysAskPolicy object`
65246073
65256074 Tool calls require user confirmation before execution.
65266075
65276076 - `type: "read"`
65286077
6529 - `"read"`
6530
6531 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
6078 - `BetaManagedAgentsWriteToolConfig object`
65326079
65336080 Configuration for the write tool.
65346081
from line 6083
65366083
65376084 - `name: "write"`
65386085
6539 - `"write"`
6540
65416086 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
65426087
65436088 Permission policy for tool execution.
65446089
6545 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6090 - `BetaManagedAgentsAlwaysAllowPolicy object`
65466091
65476092 Tool calls are automatically approved without user confirmation.
65486093
6549 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6094 - `BetaManagedAgentsAlwaysAskPolicy object`
65506095
65516096 Tool calls require user confirmation before execution.
65526097
65536098 - `type: "write"`
65546099
6555 - `"write"`
6556
6557 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
6100 - `BetaManagedAgentsGlobToolConfig object`
65586101
65596102 Configuration for the glob tool.
65606103
from line 6105
65626105
65636106 - `name: "glob"`
65646107
6565 - `"glob"`
6566
65676108 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
65686109
65696110 Permission policy for tool execution.
65706111
6571 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6112 - `BetaManagedAgentsAlwaysAllowPolicy object`
65726113
65736114 Tool calls are automatically approved without user confirmation.
65746115
6575 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6116 - `BetaManagedAgentsAlwaysAskPolicy object`
65766117
65776118 Tool calls require user confirmation before execution.
65786119
65796120 - `type: "glob"`
65806121
6581 - `"glob"`
6582
6583 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
6122 - `BetaManagedAgentsGrepToolConfig object`
65846123
65856124 Configuration for the grep tool.
65866125
from line 6127
65886127
65896128 - `name: "grep"`
65906129
6591 - `"grep"`
6592
65936130 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
65946131
65956132 Permission policy for tool execution.
65966133
6597 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6134 - `BetaManagedAgentsAlwaysAllowPolicy object`
65986135
65996136 Tool calls are automatically approved without user confirmation.
66006137
6601 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6138 - `BetaManagedAgentsAlwaysAskPolicy object`
66026139
66036140 Tool calls require user confirmation before execution.
66046141
66056142 - `type: "grep"`
66066143
6607 - `"grep"`
6608
6609 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
6144 - `BetaManagedAgentsWebFetchToolConfig object`
66106145
66116146 Configuration for the web_fetch tool.
66126147
from line 6149
66146149
66156150 - `name: "web_fetch"`
66166151
6617 - `"web_fetch"`
6618
66196152 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
66206153
66216154 Permission policy for tool execution.
66226155
6623 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6156 - `BetaManagedAgentsAlwaysAllowPolicy object`
66246157
66256158 Tool calls are automatically approved without user confirmation.
66266159
6627 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6160 - `BetaManagedAgentsAlwaysAskPolicy object`
66286161
66296162 Tool calls require user confirmation before execution.
66306163
66316164 - `type: "web_fetch"`
66326165
6633 - `"web_fetch"`
6634
66356166 - `allowed_domains: optional array of string`
66366167
66376168 - `blocked_domains: optional array of string`
66386169
66396170 - `max_content_tokens: optional number or null`
66406171
6641 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
6172 format: int32
6173
6174 - `BetaManagedAgentsWebSearchToolConfig object`
66426175
66436176 Configuration for the web_search tool.
66446177
from line 6179
66466179
66476180 - `name: "web_search"`
66486181
6649 - `"web_search"`
6650
66516182 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
66526183
66536184 Permission policy for tool execution.
66546185
6655 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6186 - `BetaManagedAgentsAlwaysAllowPolicy object`
66566187
66576188 Tool calls are automatically approved without user confirmation.
66586189
6659 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6190 - `BetaManagedAgentsAlwaysAskPolicy object`
66606191
66616192 Tool calls require user confirmation before execution.
66626193
66636194 - `type: "web_search"`
66646195
6665 - `"web_search"`
6666
66676196 - `allowed_domains: optional array of string`
66686197
66696198 - `blocked_domains: optional array of string`
from line 6205
66766205
66776206 Location precision. Only "approximate" is supported.
66786207
6679 - `"approximate"`
6680
66816208 - `city: optional string or null`
66826209
66836210 City name.
66846211
6212 minLength: 1, maxLength: 255
6213
66856214 - `country: optional string or null`
66866215
66876216 Two-letter ISO 3166-1 country code, uppercase.
from line 6219
66906219
66916220 Region or state name.
66926221
6222 minLength: 1, maxLength: 255
6223
66936224 - `timezone: optional string or null`
66946225
66956226 IANA timezone identifier, e.g. "America/Los_Angeles".
66966227
6228 minLength: 1, maxLength: 255
6229
66976230 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
66986231
66996232 Resolved default configuration for agent tools.
from line 6237
67046237
67056238 Permission policy for tool execution.
67066239
6707 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6240 - `BetaManagedAgentsAlwaysAllowPolicy object`
67086241
67096242 Tool calls are automatically approved without user confirmation.
67106243
6711 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6244 - `BetaManagedAgentsAlwaysAskPolicy object`
67126245
67136246 Tool calls require user confirmation before execution.
67146247
67156248 - `type: "agent_toolset_20260401"`
67166249
6717 - `"agent_toolset_20260401"`
6718
67196250### Beta Managed Agents Agent Toolset20260401 Bash Input
67206251
6721- `BetaManagedAgentsAgentToolset20260401BashInput object { command, restart, timeout_ms }`
6252- `BetaManagedAgentsAgentToolset20260401BashInput object`
67226253
67236254 Input payload for the `bash` tool of the
67246255 `agent_toolset_20260401` toolset. All fields are optional;
from line 6271
67406271 Per-call timeout in milliseconds. Defaults to the
67416272 runner-wide tool timeout when omitted or zero.
67426273
6274 minimum: 0
6275
67436276### Beta Managed Agents Agent Toolset20260401 Edit Input
67446277
6745- `BetaManagedAgentsAgentToolset20260401EditInput object { file_path, new_string, old_string, replace_all }`
6278- `BetaManagedAgentsAgentToolset20260401EditInput object`
67466279
67476280 Input payload for the `edit` tool. Performs a string
67486281 replacement in the named file; by default `old_string` must
from line 6300
67676300
67686301### Beta Managed Agents Agent Toolset20260401 Glob Input
67696302
6770- `BetaManagedAgentsAgentToolset20260401GlobInput object { pattern, path }`
6303- `BetaManagedAgentsAgentToolset20260401GlobInput object`
67716304
67726305 Input payload for the `glob` tool. Returns paths matching a
67736306 doublestar glob pattern, newest first.
from line 6318
67856318
67866319### Beta Managed Agents Agent Toolset20260401 Grep Input
67876320
6788- `BetaManagedAgentsAgentToolset20260401GrepInput object { pattern, path }`
6321- `BetaManagedAgentsAgentToolset20260401GrepInput object`
67896322
67906323 Input payload for the `grep` tool. Searches file contents for
67916324 a regular expression, returning matching lines.
from line 6334
68016334
68026335### Beta Managed Agents Agent Toolset20260401 Params
68036336
6804- `BetaManagedAgentsAgentToolset20260401Params object { type, configs, default_config }`
6337- `BetaManagedAgentsAgentToolset20260401Params object`
68056338
68066339 Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.
68076340
68086341 - `type: "agent_toolset_20260401"`
68096342
6810 - `"agent_toolset_20260401"`
6811
68126343 - `configs: optional array of BetaManagedAgentsAgentToolConfigParams`
68136344
68146345 Per-tool configuration overrides.
68156346
6816 - `BetaManagedAgentsBashToolConfigParams object { name, enabled, permission_policy, type }`
6347 - `BetaManagedAgentsBashToolConfigParams object`
68176348
68186349 Configuration override for the bash tool.
68196350
from line 6352
68216352
68226353 Must be "bash".
68236354
6824 - `"bash"`
6825
68266355 - `enabled: optional boolean or null`
68276356
68286357 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 6360
68316360
68326361 Permission policy for tool execution.
68336362
6834 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6363 - `BetaManagedAgentsAlwaysAllowPolicy object`
68356364
68366365 Tool calls are automatically approved without user confirmation.
68376366
68386367 - `type: "always_allow"`
68396368
6840 - `"always_allow"`
6841
6842 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6369 - `BetaManagedAgentsAlwaysAskPolicy object`
68436370
68446371 Tool calls require user confirmation before execution.
68456372
68466373 - `type: "always_ask"`
68476374
6848 - `"always_ask"`
6849
68506375 - `type: optional "bash"`
68516376
6852 - `"bash"`
6853
6854 - `BetaManagedAgentsEditToolConfigParams object { name, enabled, permission_policy, type }`
6377 - `BetaManagedAgentsEditToolConfigParams object`
68556378
68566379 Configuration override for the edit tool.
68576380
from line 6382
68596382
68606383 Must be "edit".
68616384
6862 - `"edit"`
6863
68646385 - `enabled: optional boolean or null`
68656386
68666387 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 6390
68696390
68706391 Permission policy for tool execution.
68716392
6872 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6393 - `BetaManagedAgentsAlwaysAllowPolicy object`
68736394
68746395 Tool calls are automatically approved without user confirmation.
68756396
6876 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6397 - `BetaManagedAgentsAlwaysAskPolicy object`
68776398
68786399 Tool calls require user confirmation before execution.
68796400
68806401 - `type: optional "edit"`
68816402
6882 - `"edit"`
6883
6884 - `BetaManagedAgentsReadToolConfigParams object { name, enabled, permission_policy, type }`
6403 - `BetaManagedAgentsReadToolConfigParams object`
68856404
68866405 Configuration override for the read tool.
68876406
from line 6408
68896408
68906409 Must be "read".
68916410
6892 - `"read"`
6893
68946411 - `enabled: optional boolean or null`
68956412
68966413 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 6416
68996416
69006417 Permission policy for tool execution.
69016418
6902 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6419 - `BetaManagedAgentsAlwaysAllowPolicy object`
69036420
69046421 Tool calls are automatically approved without user confirmation.
69056422
6906 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6423 - `BetaManagedAgentsAlwaysAskPolicy object`
69076424
69086425 Tool calls require user confirmation before execution.
69096426
69106427 - `type: optional "read"`
69116428
6912 - `"read"`
6913
6914 - `BetaManagedAgentsWriteToolConfigParams object { name, enabled, permission_policy, type }`
6429 - `BetaManagedAgentsWriteToolConfigParams object`
69156430
69166431 Configuration override for the write tool.
69176432
from line 6434
69196434
69206435 Must be "write".
69216436
6922 - `"write"`
6923
69246437 - `enabled: optional boolean or null`
69256438
69266439 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 6442
69296442
69306443 Permission policy for tool execution.
69316444
6932 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6445 - `BetaManagedAgentsAlwaysAllowPolicy object`
69336446
69346447 Tool calls are automatically approved without user confirmation.
69356448
6936 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6449 - `BetaManagedAgentsAlwaysAskPolicy object`
69376450
69386451 Tool calls require user confirmation before execution.
69396452
69406453 - `type: optional "write"`
69416454
6942 - `"write"`
6943
6944 - `BetaManagedAgentsGlobToolConfigParams object { name, enabled, permission_policy, type }`
6455 - `BetaManagedAgentsGlobToolConfigParams object`
69456456
69466457 Configuration override for the glob tool.
69476458
from line 6460
69496460
69506461 Must be "glob".
69516462
6952 - `"glob"`
6953
69546463 - `enabled: optional boolean or null`
69556464
69566465 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 6468
69596468
69606469 Permission policy for tool execution.
69616470
6962 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6471 - `BetaManagedAgentsAlwaysAllowPolicy object`
69636472
69646473 Tool calls are automatically approved without user confirmation.
69656474
6966 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6475 - `BetaManagedAgentsAlwaysAskPolicy object`
69676476
69686477 Tool calls require user confirmation before execution.
69696478
69706479 - `type: optional "glob"`
69716480
6972 - `"glob"`
6973
6974 - `BetaManagedAgentsGrepToolConfigParams object { name, enabled, permission_policy, type }`
6481 - `BetaManagedAgentsGrepToolConfigParams object`
69756482
69766483 Configuration override for the grep tool.
69776484
from line 6486
69796486
69806487 Must be "grep".
69816488
6982 - `"grep"`
6983
69846489 - `enabled: optional boolean or null`
69856490
69866491 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 6494
69896494
69906495 Permission policy for tool execution.
69916496
6992 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6497 - `BetaManagedAgentsAlwaysAllowPolicy object`
69936498
69946499 Tool calls are automatically approved without user confirmation.
69956500
6996 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6501 - `BetaManagedAgentsAlwaysAskPolicy object`
69976502
69986503 Tool calls require user confirmation before execution.
69996504
70006505 - `type: optional "grep"`
70016506
7002 - `"grep"`
7003
7004 - `BetaManagedAgentsWebFetchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }`
6507 - `BetaManagedAgentsWebFetchToolConfigParams object`
70056508
70066509 Configuration override for the web_fetch tool.
70076510
from line 6512
70096512
70106513 Must be "web_fetch".
70116514
7012 - `"web_fetch"`
7013
70146515 - `allowed_domains: optional array of string`
70156516
70166517 Only fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
from line 6528
70276528
70286529 Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs.
70296530
6531 format: int32
6532
70306533 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
70316534
70326535 Permission policy for tool execution.
70336536
7034 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6537 - `BetaManagedAgentsAlwaysAllowPolicy object`
70356538
70366539 Tool calls are automatically approved without user confirmation.
70376540
7038 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6541 - `BetaManagedAgentsAlwaysAskPolicy object`
70396542
70406543 Tool calls require user confirmation before execution.
70416544
70426545 - `type: optional "web_fetch"`
70436546
7044 - `"web_fetch"`
7045
7046 - `BetaManagedAgentsWebSearchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }`
6547 - `BetaManagedAgentsWebSearchToolConfigParams object`
70476548
70486549 Configuration override for the web_search tool.
70496550
from line 6552
70516552
70526553 Must be "web_search".
70536554
7054 - `"web_search"`
7055
70566555 - `allowed_domains: optional array of string`
70576556
70586557 Only return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
from line 6568
70696568
70706569 Permission policy for tool execution.
70716570
7072 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6571 - `BetaManagedAgentsAlwaysAllowPolicy object`
70736572
70746573 Tool calls are automatically approved without user confirmation.
70756574
7076 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6575 - `BetaManagedAgentsAlwaysAskPolicy object`
70776576
70786577 Tool calls require user confirmation before execution.
70796578
70806579 - `type: optional "web_search"`
70816580
7082 - `"web_search"`
7083
70846581 - `user_location: optional BetaManagedAgentsUserLocation or null`
70856582
70866583 Approximate user location for search result localization.
from line 6586
70896586
70906587 Location precision. Only "approximate" is supported.
70916588
7092 - `"approximate"`
7093
70946589 - `city: optional string or null`
70956590
70966591 City name.
70976592
6593 minLength: 1, maxLength: 255
6594
70986595 - `country: optional string or null`
70996596
71006597 Two-letter ISO 3166-1 country code, uppercase.
from line 6600
71036600
71046601 Region or state name.
71056602
6603 minLength: 1, maxLength: 255
6604
71066605 - `timezone: optional string or null`
71076606
71086607 IANA timezone identifier, e.g. "America/Los_Angeles".
71096608
6609 minLength: 1, maxLength: 255
6610
71106611 - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or null`
71116612
71126613 Default configuration for all tools in a toolset.
from line 6620
71196620
71206621 Permission policy for tool execution.
71216622
7122 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6623 - `BetaManagedAgentsAlwaysAllowPolicy object`
71236624
71246625 Tool calls are automatically approved without user confirmation.
71256626
7126 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6627 - `BetaManagedAgentsAlwaysAskPolicy object`
71276628
71286629 Tool calls require user confirmation before execution.
71296630
71306631### Beta Managed Agents Agent Toolset20260401 Read Input
71316632
7132- `BetaManagedAgentsAgentToolset20260401ReadInput object { file_path, view_range }`
6633- `BetaManagedAgentsAgentToolset20260401ReadInput object`
71336634
71346635 Input payload for the `read` tool. Reads file contents
71356636 relative to the runner's working directory (or absolute when
from line 6646
71456646 range. When omitted the entire file is returned.
71466647 `end_line` of 0 or negative means "to end of file".
71476648
6649 minItems: 2, maxItems: 2
6650
71486651### Beta Managed Agents Agent Toolset20260401 Write Input
71496652
7150- `BetaManagedAgentsAgentToolset20260401WriteInput object { content, file_path }`
6653- `BetaManagedAgentsAgentToolset20260401WriteInput object`
71516654
71526655 Input payload for the `write` tool. Writes (overwriting) the
71536656 entire file contents.
from line 6665
71626665
71636666### Beta Managed Agents Always Allow Policy
71646667
7165- `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6668- `BetaManagedAgentsAlwaysAllowPolicy object`
71666669
71676670 Tool calls are automatically approved without user confirmation.
71686671
71696672 - `type: "always_allow"`
71706673
7171 - `"always_allow"`
7172
71736674### Beta Managed Agents Always Ask Policy
71746675
7175- `BetaManagedAgentsAlwaysAskPolicy object { type }`
6676- `BetaManagedAgentsAlwaysAskPolicy object`
71766677
71776678 Tool calls require user confirmation before execution.
71786679
71796680 - `type: "always_ask"`
71806681
7181 - `"always_ask"`
7182
71836682### Beta Managed Agents Anthropic Skill
71846683
7185- `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
6684- `BetaManagedAgentsAnthropicSkill object`
71866685
71876686 A resolved Anthropic-managed skill.
71886687
from line 6689
71906689
71916690 - `type: "anthropic"`
71926691
7193 - `"anthropic"`
7194
71956692 - `version: string`
71966693
71976694### Beta Managed Agents Anthropic Skill Params
71986695
7199- `BetaManagedAgentsAnthropicSkillParams object { skill_id, type, version }`
6696- `BetaManagedAgentsAnthropicSkillParams object`
72006697
72016698 An Anthropic-managed skill.
72026699
from line 6701
72046701
72056702 Identifier of the Anthropic skill (e.g., "xlsx").
72066703
6704 minLength: 1, maxLength: 64
6705
72076706 - `type: "anthropic"`
72086707
7209 - `"anthropic"`
7210
72116708 - `version: optional string or null`
72126709
72136710 Version to pin. Defaults to latest if omitted.
72146711
6712 minLength: 1, maxLength: 64
6713
72156714### Beta Managed Agents Bash Tool Config
72166715
7217- `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
6716- `BetaManagedAgentsBashToolConfig object`
72186717
72196718 Configuration for the bash tool.
72206719
from line 6721
72226721
72236722 - `name: "bash"`
72246723
7225 - `"bash"`
7226
72276724 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
72286725
72296726 Permission policy for tool execution.
72306727
7231 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6728 - `BetaManagedAgentsAlwaysAllowPolicy object`
72326729
72336730 Tool calls are automatically approved without user confirmation.
72346731
72356732 - `type: "always_allow"`
72366733
7237 - `"always_allow"`
7238
7239 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6734 - `BetaManagedAgentsAlwaysAskPolicy object`
72406735
72416736 Tool calls require user confirmation before execution.
72426737
72436738 - `type: "always_ask"`
72446739
7245 - `"always_ask"`
7246
72476740 - `type: "bash"`
72486741
7249 - `"bash"`
7250
72516742### Beta Managed Agents Bash Tool Config Params
72526743
7253- `BetaManagedAgentsBashToolConfigParams object { name, enabled, permission_policy, type }`
6744- `BetaManagedAgentsBashToolConfigParams object`
72546745
72556746 Configuration override for the bash tool.
72566747
from line 6749
72586749
72596750 Must be "bash".
72606751
7261 - `"bash"`
7262
72636752 - `enabled: optional boolean or null`
72646753
72656754 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 6757
72686757
72696758 Permission policy for tool execution.
72706759
7271 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6760 - `BetaManagedAgentsAlwaysAllowPolicy object`
72726761
72736762 Tool calls are automatically approved without user confirmation.
72746763
72756764 - `type: "always_allow"`
72766765
7277 - `"always_allow"`
7278
7279 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6766 - `BetaManagedAgentsAlwaysAskPolicy object`
72806767
72816768 Tool calls require user confirmation before execution.
72826769
72836770 - `type: "always_ask"`
72846771
7285 - `"always_ask"`
7286
72876772 - `type: optional "bash"`
72886773
7289 - `"bash"`
7290
72916774### Beta Managed Agents Custom Skill
72926775
7293- `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
6776- `BetaManagedAgentsCustomSkill object`
72946777
72956778 A resolved user-created custom skill.
72966779
from line 6781
72986781
72996782 - `type: "custom"`
73006783
7301 - `"custom"`
7302
73036784 - `version: string`
73046785
73056786### Beta Managed Agents Custom Skill Params
73066787
7307- `BetaManagedAgentsCustomSkillParams object { skill_id, type, version }`
6788- `BetaManagedAgentsCustomSkillParams object`
73086789
73096790 A user-created custom skill.
73106791
from line 6793
73126793
73136794 Tagged ID of the custom skill (e.g., "skill_01XJ5...").
73146795
6796 minLength: 1, maxLength: 64
6797
73156798 - `type: "custom"`
73166799
7317 - `"custom"`
7318
73196800 - `version: optional string or null`
73206801
73216802 Version to pin. Defaults to latest if omitted.
73226803
6804 minLength: 1, maxLength: 64
6805
73236806### Beta Managed Agents Custom Tool
73246807
7325- `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
6808- `BetaManagedAgentsCustomTool object`
73266809
73276810 A custom tool as returned in API responses.
73286811
from line 6817
73346817
73356818 - `type: "object"`
73366819
7337 - `"object"`
7338
73396820 - `properties: optional map[unknown] or null`
73406821
73416822 - `required: optional array of string or null`
from line 6825
73446825
73456826 - `type: "custom"`
73466827
7347 - `"custom"`
7348
73496828### Beta Managed Agents Custom Tool Input Schema
73506829
7351- `BetaManagedAgentsCustomToolInputSchema object { type, properties, required }`
6830- `BetaManagedAgentsCustomToolInputSchema object`
73526831
73536832 JSON Schema for custom tool input parameters.
73546833
73556834 - `type: "object"`
73566835
7357 - `"object"`
7358
73596836 - `properties: optional map[unknown] or null`
73606837
73616838 - `required: optional array of string or null`
73626839
73636840### Beta Managed Agents Custom Tool Params
73646841
7365- `BetaManagedAgentsCustomToolParams object { description, input_schema, name, type }`
6842- `BetaManagedAgentsCustomToolParams object`
73666843
73676844 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.
73686845
from line 6847
73706847
73716848 Description of what the tool does, shown to the agent to help it decide when to use the tool.
73726849
6850 minLength: 1
6851
73736852 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
73746853
73756854 JSON Schema for custom tool input parameters.
73766855
73776856 - `type: "object"`
73786857
7379 - `"object"`
7380
73816858 - `properties: optional map[unknown] or null`
73826859
73836860 - `required: optional array of string or null`
from line 6863
73866863
73876864 Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.
73886865
6866 minLength: 1, maxLength: 128
6867
73896868 - `type: "custom"`
73906869
7391 - `"custom"`
7392
73936870### Beta Managed Agents Edit Tool Config
73946871
7395- `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
6872- `BetaManagedAgentsEditToolConfig object`
73966873
73976874 Configuration for the edit tool.
73986875
from line 6877
74006877
74016878 - `name: "edit"`
74026879
7403 - `"edit"`
7404
74056880 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
74066881
74076882 Permission policy for tool execution.
74086883
7409 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6884 - `BetaManagedAgentsAlwaysAllowPolicy object`
74106885
74116886 Tool calls are automatically approved without user confirmation.
74126887
74136888 - `type: "always_allow"`
74146889
7415 - `"always_allow"`
7416
7417 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6890 - `BetaManagedAgentsAlwaysAskPolicy object`
74186891
74196892 Tool calls require user confirmation before execution.
74206893
74216894 - `type: "always_ask"`
74226895
7423 - `"always_ask"`
7424
74256896 - `type: "edit"`
74266897
7427 - `"edit"`
7428
74296898### Beta Managed Agents Edit Tool Config Params
74306899
7431- `BetaManagedAgentsEditToolConfigParams object { name, enabled, permission_policy, type }`
6900- `BetaManagedAgentsEditToolConfigParams object`
74326901
74336902 Configuration override for the edit tool.
74346903
from line 6905
74366905
74376906 Must be "edit".
74386907
7439 - `"edit"`
7440
74416908 - `enabled: optional boolean or null`
74426909
74436910 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 6913
74466913
74476914 Permission policy for tool execution.
74486915
7449 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6916 - `BetaManagedAgentsAlwaysAllowPolicy object`
74506917
74516918 Tool calls are automatically approved without user confirmation.
74526919
74536920 - `type: "always_allow"`
74546921
7455 - `"always_allow"`
7456
7457 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6922 - `BetaManagedAgentsAlwaysAskPolicy object`
74586923
74596924 Tool calls require user confirmation before execution.
74606925
74616926 - `type: "always_ask"`
74626927
7463 - `"always_ask"`
7464
74656928 - `type: optional "edit"`
74666929
7467 - `"edit"`
7468
74696930### Beta Managed Agents Effort High
74706931
7471- `BetaManagedAgentsEffortHigh object { type }`
6932- `BetaManagedAgentsEffortHigh object`
74726933
74736934 High effort. Favors reasoning depth.
74746935
74756936 - `type: "high"`
74766937
7477 - `"high"`
7478
74796938### Beta Managed Agents Effort Low
74806939
7481- `BetaManagedAgentsEffortLow object { type }`
6940- `BetaManagedAgentsEffortLow object`
74826941
74836942 Low effort. Favors latency over reasoning depth.
74846943
74856944 - `type: "low"`
74866945
7487 - `"low"`
7488
74896946### Beta Managed Agents Effort Max
74906947
7491- `BetaManagedAgentsEffortMax object { type }`
6948- `BetaManagedAgentsEffortMax object`
74926949
74936950 Maximum effort. Favors reasoning depth over latency.
74946951
74956952 - `type: "max"`
74966953
7497 - `"max"`
7498
74996954### Beta Managed Agents Effort Medium
75006955
7501- `BetaManagedAgentsEffortMedium object { type }`
6956- `BetaManagedAgentsEffortMedium object`
75026957
75036958 Medium effort. Balances latency and reasoning depth.
75046959
75056960 - `type: "medium"`
75066961
7507 - `"medium"`
7508
75096962### Beta Managed Agents Effort Xhigh
75106963
7511- `BetaManagedAgentsEffortXhigh object { type }`
6964- `BetaManagedAgentsEffortXhigh object`
75126965
75136966 Extra-high effort. Not all models accept this level.
75146967
75156968 - `type: "xhigh"`
75166969
7517 - `"xhigh"`
7518
75196970### Beta Managed Agents Glob Tool Config
75206971
7521- `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
6972- `BetaManagedAgentsGlobToolConfig object`
75226973
75236974 Configuration for the glob tool.
75246975
from line 6977
75266977
75276978 - `name: "glob"`
75286979
7529 - `"glob"`
7530
75316980 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
75326981
75336982 Permission policy for tool execution.
75346983
7535 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
6984 - `BetaManagedAgentsAlwaysAllowPolicy object`
75366985
75376986 Tool calls are automatically approved without user confirmation.
75386987
75396988 - `type: "always_allow"`
75406989
7541 - `"always_allow"`
7542
7543 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
6990 - `BetaManagedAgentsAlwaysAskPolicy object`
75446991
75456992 Tool calls require user confirmation before execution.
75466993
75476994 - `type: "always_ask"`
75486995
7549 - `"always_ask"`
7550
75516996 - `type: "glob"`
75526997
7553 - `"glob"`
7554
75556998### Beta Managed Agents Glob Tool Config Params
75566999
7557- `BetaManagedAgentsGlobToolConfigParams object { name, enabled, permission_policy, type }`
7000- `BetaManagedAgentsGlobToolConfigParams object`
75587001
75597002 Configuration override for the glob tool.
75607003
from line 7005
75627005
75637006 Must be "glob".
75647007
7565 - `"glob"`
7566
75677008 - `enabled: optional boolean or null`
75687009
75697010 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 7013
75727013
75737014 Permission policy for tool execution.
75747015
7575 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
7016 - `BetaManagedAgentsAlwaysAllowPolicy object`
75767017
75777018 Tool calls are automatically approved without user confirmation.
75787019
75797020 - `type: "always_allow"`
75807021
7581 - `"always_allow"`
7582
7583 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
7022 - `BetaManagedAgentsAlwaysAskPolicy object`
75847023
75857024 Tool calls require user confirmation before execution.
75867025
75877026 - `type: "always_ask"`
75887027
7589 - `"always_ask"`
7590
75917028 - `type: optional "glob"`
75927029
7593 - `"glob"`
7594
75957030### Beta Managed Agents Grep Tool Config
75967031
7597- `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
7032- `BetaManagedAgentsGrepToolConfig object`
75987033
75997034 Configuration for the grep tool.
76007035
from line 7037
76027037
76037038 - `name: "grep"`
76047039
7605 - `"grep"`
7606
76077040 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
76087041
76097042 Permission policy for tool execution.
76107043
7611 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
7044 - `BetaManagedAgentsAlwaysAllowPolicy object`
76127045
76137046 Tool calls are automatically approved without user confirmation.
76147047
76157048 - `type: "always_allow"`
76167049
7617 - `"always_allow"`
7618
7619 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
7050 - `BetaManagedAgentsAlwaysAskPolicy object`
76207051
76217052 Tool calls require user confirmation before execution.
76227053
76237054 - `type: "always_ask"`
76247055
7625 - `"always_ask"`
7626
76277056 - `type: "grep"`
76287057
7629 - `"grep"`
7630
76317058### Beta Managed Agents Grep Tool Config Params
76327059
7633- `BetaManagedAgentsGrepToolConfigParams object { name, enabled, permission_policy, type }`
7060- `BetaManagedAgentsGrepToolConfigParams object`
76347061
76357062 Configuration override for the grep tool.
76367063
from line 7065
76387065
76397066 Must be "grep".
76407067
7641 - `"grep"`
7642
76437068 - `enabled: optional boolean or null`
76447069
76457070 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 7073
76487073
76497074 Permission policy for tool execution.
76507075
7651 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
7076 - `BetaManagedAgentsAlwaysAllowPolicy object`
76527077
76537078 Tool calls are automatically approved without user confirmation.
76547079
76557080 - `type: "always_allow"`
76567081
7657 - `"always_allow"`
7658
7659 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
7082 - `BetaManagedAgentsAlwaysAskPolicy object`
76607083
76617084 Tool calls require user confirmation before execution.
76627085
76637086 - `type: "always_ask"`
76647087
7665 - `"always_ask"`
7666
76677088 - `type: optional "grep"`
76687089
7669 - `"grep"`
7670
76717090### Beta Managed Agents MCP Server URL Definition
76727091
7673- `BetaManagedAgentsMCPServerURLDefinition object { name, type, url }`
7092- `BetaManagedAgentsMCPServerURLDefinition object`
76747093
76757094 URL-based MCP server connection as returned in API responses.
76767095
from line 7097
76787097
76797098 - `type: "url"`
76807099
7681 - `"url"`
7682
76837100 - `url: string`
76847101
76857102### Beta Managed Agents MCP Tool Config
76867103
7687- `BetaManagedAgentsMCPToolConfig object { enabled, name, permission_policy }`
7104- `BetaManagedAgentsMCPToolConfig object`
76887105
76897106 Resolved configuration for a specific MCP tool.
76907107
from line 7113
76967113
76977114 Permission policy for tool execution.
76987115
7699 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
7116 - `BetaManagedAgentsAlwaysAllowPolicy object`
77007117
77017118 Tool calls are automatically approved without user confirmation.
77027119
77037120 - `type: "always_allow"`
77047121
7705 - `"always_allow"`
7706
7707 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
7122 - `BetaManagedAgentsAlwaysAskPolicy object`
77087123
77097124 Tool calls require user confirmation before execution.
77107125
77117126 - `type: "always_ask"`
77127127
7713 - `"always_ask"`
7714
77157128### Beta Managed Agents MCP Tool Config Params
77167129
7717- `BetaManagedAgentsMCPToolConfigParams object { name, enabled, permission_policy }`
7130- `BetaManagedAgentsMCPToolConfigParams object`
77187131
77197132 Configuration override for a specific MCP tool.
77207133
from line 7135
77227135
77237136 Name of the MCP tool to configure. 1-128 characters.
77247137
7138 minLength: 1, maxLength: 128
7139
77257140 - `enabled: optional boolean or null`
77267141
77277142 Whether this tool is enabled. Overrides the `default_config` setting.
from line 7145
77307145
77317146 Permission policy for tool execution.
77327147
7733 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
7148 - `BetaManagedAgentsAlwaysAllowPolicy object`
77347149
77357150 Tool calls are automatically approved without user confirmation.
77367151
77377152 - `type: "always_allow"`
77387153
7739 - `"always_allow"`
7740
7741 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
7154 - `BetaManagedAgentsAlwaysAskPolicy object`
77427155
77437156 Tool calls require user confirmation before execution.
77447157
77457158 - `type: "always_ask"`
77467159
7747 - `"always_ask"`
7748
77497160### Beta Managed Agents MCP Toolset
77507161
7751- `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
7162- `BetaManagedAgentsMCPToolset object`
77527163
77537164 - `configs: array of BetaManagedAgentsMCPToolConfig`
77547165
from line 7171
77607171
77617172 Permission policy for tool execution.
77627173
7763 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
7174 - `BetaManagedAgentsAlwaysAllowPolicy object`
77647175
77657176 Tool calls are automatically approved without user confirmation.
77667177
77677178 - `type: "always_allow"`
77687179
7769 - `"always_allow"`
7770
7771 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
7180 - `BetaManagedAgentsAlwaysAskPolicy object`
77727181
77737182 Tool calls require user confirmation before execution.
77747183
77757184 - `type: "always_ask"`
77767185
7777 - `"always_ask"`
7778
77797186 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
77807187
77817188 Resolved default configuration for all tools from an MCP server.
from line 7193
77867193
77877194 Permission policy for tool execution.
77887195
7789 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
7196 - `BetaManagedAgentsAlwaysAllowPolicy object`
77907197
77917198 Tool calls are automatically approved without user confirmation.
77927199
7793 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
7200 - `BetaManagedAgentsAlwaysAskPolicy object`
77947201
77957202 Tool calls require user confirmation before execution.
77967203
from line 7205
77987205
77997206 - `type: "mcp_toolset"`
78007207
7801 - `"mcp_toolset"`
7802
78037208### Beta Managed Agents MCP Toolset Default Config
78047209
7805- `BetaManagedAgentsMCPToolsetDefaultConfig object { enabled, permission_policy }`
7210- `BetaManagedAgentsMCPToolsetDefaultConfig object`
78067211
78077212 Resolved default configuration for all tools from an MCP server.
78087213
from line 7217
78127217
78137218 Permission policy for tool execution.
78147219
7815 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
7220 - `BetaManagedAgentsAlwaysAllowPolicy object`
78167221
78177222 Tool calls are automatically approved without user confirmation.
78187223
78197224 - `type: "always_allow"`
78207225
7821 - `"always_allow"`
7822
7823 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
7226 - `BetaManagedAgentsAlwaysAskPolicy object`
78247227
78257228 Tool calls require user confirmation before execution.
78267229
78277230 - `type: "always_ask"`
78287231
7829 - `"always_ask"`
7830
78317232### Beta Managed Agents MCP Toolset Default Config Params
78327233
7833- `BetaManagedAgentsMCPToolsetDefaultConfigParams object { enabled, permission_policy }`
7234- `BetaManagedAgentsMCPToolsetDefaultConfigParams object`
78347235
78357236 Default configuration for all tools from an MCP server.
78367237
from line 7243
78427243
78437244 Permission policy for tool execution.
78447245
7845 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
7246 - `BetaManagedAgentsAlwaysAllowPolicy object`
78467247
78477248 Tool calls are automatically approved without user confirmation.
78487249
78497250 - `type: "always_allow"`
78507251
7851 - `"always_allow"`
7852
7853 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
7252 - `BetaManagedAgentsAlwaysAskPolicy object`
78547253
78557254 Tool calls require user confirmation before execution.
78567255
78577256 - `type: "always_ask"`
78587257
7859 - `"always_ask"`
7860
78617258### Beta Managed Agents MCP Toolset Params
78627259
7863- `BetaManagedAgentsMCPToolsetParams object { mcp_server_name, type, configs, default_config }`
7260- `BetaManagedAgentsMCPToolsetParams object`
78647261
78657262 Configuration for tools from an MCP server defined in `mcp_servers`.
78667263
from line 7265
78687265
78697266 Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.
78707267
7268 minLength: 1, maxLength: 255
7269
78717270 - `type: "mcp_toolset"`
78727271
7873 - `"mcp_toolset"`
7874
78757272 - `configs: optional array of BetaManagedAgentsMCPToolConfigParams`
78767273
78777274 Per-tool configuration overrides.
from line 7277
78807277
78817278 Name of the MCP tool to configure. 1-128 characters.
78827279
7280 minLength: 1, maxLength: 128
7281
78837282 - `enabled: optional boolean or null`
78847283
78857284 Whether this tool is enabled. Overrides the `default_config` setting.
from line 7287
78887287
78897288 Permission policy for tool execution.
78907289
7891 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
7290 - `BetaManagedAgentsAlwaysAllowPolicy object`
78927291
78937292 Tool calls are automatically approved without user confirmation.
78947293
78957294 - `type: "always_allow"`
78967295
7897 - `"always_allow"`
7898
7899 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
7296 - `BetaManagedAgentsAlwaysAskPolicy object`
79007297
79017298 Tool calls require user confirmation before execution.
79027299
79037300 - `type: "always_ask"`
79047301
7905 - `"always_ask"`
7906
79077302 - `default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or null`
79087303
79097304 Default configuration for all tools from an MCP server.
from line 7311
79167311
79177312 Permission policy for tool execution.
79187313
7919 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
7314 - `BetaManagedAgentsAlwaysAllowPolicy object`
79207315
79217316 Tool calls are automatically approved without user confirmation.
79227317
7923 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
7318 - `BetaManagedAgentsAlwaysAskPolicy object`
79247319
79257320 Tool calls require user confirmation before execution.
79267321
from line 7389
79947389
79957390### Beta Managed Agents Model Config
79967391
7997- `BetaManagedAgentsModelConfig object { id, effort, inference_geo, speed }`
7392- `BetaManagedAgentsModelConfig object`
79987393
79997394 Model identifier and configuration.
80007395
from line 7463
80687463
80697464 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
80707465
8071 - `BetaManagedAgentsEffortLow object { type }`
7466 - `BetaManagedAgentsEffortLow object`
80727467
80737468 Low effort. Favors latency over reasoning depth.
80747469
80757470 - `type: "low"`
80767471
8077 - `"low"`
8078
8079 - `BetaManagedAgentsEffortMedium object { type }`
7472 - `BetaManagedAgentsEffortMedium object`
80807473
80817474 Medium effort. Balances latency and reasoning depth.
80827475
80837476 - `type: "medium"`
80847477
8085 - `"medium"`
8086
8087 - `BetaManagedAgentsEffortHigh object { type }`
7478 - `BetaManagedAgentsEffortHigh object`
80887479
80897480 High effort. Favors reasoning depth.
80907481
80917482 - `type: "high"`
80927483
8093 - `"high"`
8094
8095 - `BetaManagedAgentsEffortXhigh object { type }`
7484 - `BetaManagedAgentsEffortXhigh object`
80967485
80977486 Extra-high effort. Not all models accept this level.
80987487
80997488 - `type: "xhigh"`
81007489
8101 - `"xhigh"`
8102
8103 - `BetaManagedAgentsEffortMax object { type }`
7490 - `BetaManagedAgentsEffortMax object`
81047491
81057492 Maximum effort. Favors reasoning depth over latency.
81067493
81077494 - `type: "max"`
81087495
8109 - `"max"`
8110
81117496 - `inference_geo: optional string`
81127497
81137498 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 7507
81227507
81237508### Beta Managed Agents Model Config Params
81247509
8125- `BetaManagedAgentsModelConfigParams object { id, effort, inference_geo, speed }`
7510- `BetaManagedAgentsModelConfigParams object`
81267511
81277512 An object that defines additional configuration control over model use
81287513
from line 7595
82107595
82117596 - `"max"`
82127597
8213 - `BetaManagedAgentsEffortLow object { type }`
7598 - `BetaManagedAgentsEffortLow object`
82147599
82157600 Low effort. Favors latency over reasoning depth.
82167601
82177602 - `type: "low"`
82187603
8219 - `"low"`
8220
8221 - `BetaManagedAgentsEffortMedium object { type }`
7604 - `BetaManagedAgentsEffortMedium object`
82227605
82237606 Medium effort. Balances latency and reasoning depth.
82247607
82257608 - `type: "medium"`
82267609
8227 - `"medium"`
8228
8229 - `BetaManagedAgentsEffortHigh object { type }`
7610 - `BetaManagedAgentsEffortHigh object`
82307611
82317612 High effort. Favors reasoning depth.
82327613
82337614 - `type: "high"`
82347615
8235 - `"high"`
8236
8237 - `BetaManagedAgentsEffortXhigh object { type }`
7616 - `BetaManagedAgentsEffortXhigh object`
82387617
82397618 Extra-high effort. Not all models accept this level.
82407619
82417620 - `type: "xhigh"`
82427621
8243 - `"xhigh"`
8244
8245 - `BetaManagedAgentsEffortMax object { type }`
7622 - `BetaManagedAgentsEffortMax object`
82467623
82477624 Maximum effort. Favors reasoning depth over latency.
82487625
82497626 - `type: "max"`
82507627
8251 - `"max"`
8252
82537628 - `inference_geo: optional string or null`
82547629
82557630 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. On update, `model` is whole-object replacement — omitting inference_geo clears it.
from line 7639
82647639
82657640### Beta Managed Agents Multiagent Coordinator
82667641
8267- `BetaManagedAgentsMultiagentCoordinator object { agents, type }`
7642- `BetaManagedAgentsMultiagentCoordinator object`
82687643
82697644 Resolved coordinator topology with a concrete agent roster.
82707645
from line 7647
82727647
82737648 Agents the coordinator may spawn as session threads, each resolved to a specific version.
82747649
8275 - `BetaManagedAgentsAgentReference object { id, type, version }`
7650 - `BetaManagedAgentsAgentReference object`
82767651
82777652 A resolved agent reference with a concrete version.
82787653
from line 7655
82807655
82817656 - `type: "agent"`
82827657
8283 - `"agent"`
8284
82857658 - `version: number`
82867659
8287 - `BetaManagedAgentsAdvisor object { model, type }`
7660 format: int32
7661
7662 - `BetaManagedAgentsAdvisor object`
82887663
82897664 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
82907665
from line 7669
82947669
82957670 - `type: "advisor"`
82967671
8297 - `"advisor"`
8298
82997672 - `type: "coordinator"`
83007673
8301 - `"coordinator"`
8302
83037674### Beta Managed Agents Multiagent Coordinator Params
83047675
8305- `BetaManagedAgentsMultiagentCoordinatorParams object { agents, type }`
7676- `BetaManagedAgentsMultiagentCoordinatorParams object`
83067677
83077678 A coordinator topology: the session's primary thread orchestrates work by spawning session threads, each running an agent drawn from the `agents` roster.
83087679
from line 7683
83127683
83137684 - `string`
83147685
8315 - `BetaManagedAgentsAgentParams object { id, type, version }`
7686 - `BetaManagedAgentsAgentParams object`
83167687
83177688 Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version
83187689
from line 7691
83207691
83217692 The `agent` ID.
83227693
7694 minLength: 1, maxLength: 128
7695
83237696 - `type: "agent"`
83247697
8325 - `"agent"`
8326
83277698 - `version: optional number`
83287699
83297700 The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.
83307701
8331 - `BetaManagedAgentsMultiagentSelfParams object { type }`
7702 format: int32
7703
7704 - `BetaManagedAgentsMultiagentSelfParams object`
83327705
83337706 Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference.
83347707
83357708 - `type: "self"`
83367709
8337 - `"self"`
8338
8339 - `BetaManagedAgentsAdvisorParams object { model, type }`
7710 - `BetaManagedAgentsAdvisorParams object`
83407711
83417712 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`.
83427713
from line 7715
83447715
83457716 A Claude model id. The model must be permitted as an advisor for this agent's model — see the sessions/threads/advisor spec.
83467717
7718 minLength: 1, maxLength: 256
7719
83477720 - `type: "advisor"`
83487721
8349 - `"advisor"`
8350
83517722 - `type: "coordinator"`
83527723
8353 - `"coordinator"`
8354
83557724### Beta Managed Agents Multiagent Self Params
83567725
8357- `BetaManagedAgentsMultiagentSelfParams object { type }`
7726- `BetaManagedAgentsMultiagentSelfParams object`
83587727
83597728 Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference.
83607729
83617730 - `type: "self"`
83627731
8363 - `"self"`
8364
83657732### Beta Managed Agents Read Tool Config
83667733
8367- `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
7734- `BetaManagedAgentsReadToolConfig object`
83687735
83697736 Configuration for the read tool.
83707737
from line 7739
83727739
83737740 - `name: "read"`
83747741
8375 - `"read"`
8376
83777742 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
83787743
83797744 Permission policy for tool execution.
83807745
8381 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
7746 - `BetaManagedAgentsAlwaysAllowPolicy object`
83827747
83837748 Tool calls are automatically approved without user confirmation.
83847749
83857750 - `type: "always_allow"`
83867751
8387 - `"always_allow"`
8388
8389 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
7752 - `BetaManagedAgentsAlwaysAskPolicy object`
83907753
83917754 Tool calls require user confirmation before execution.
83927755
83937756 - `type: "always_ask"`
83947757
8395 - `"always_ask"`
8396
83977758 - `type: "read"`
83987759
8399 - `"read"`
8400
84017760### Beta Managed Agents Read Tool Config Params
84027761
8403- `BetaManagedAgentsReadToolConfigParams object { name, enabled, permission_policy, type }`
7762- `BetaManagedAgentsReadToolConfigParams object`
84047763
84057764 Configuration override for the read tool.
84067765
from line 7767
84087767
84097768 Must be "read".
84107769
8411 - `"read"`
8412
84137770 - `enabled: optional boolean or null`
84147771
84157772 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 7775
84187775
84197776 Permission policy for tool execution.
84207777
8421 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
7778 - `BetaManagedAgentsAlwaysAllowPolicy object`
84227779
84237780 Tool calls are automatically approved without user confirmation.
84247781
84257782 - `type: "always_allow"`
84267783
8427 - `"always_allow"`
8428
8429 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
7784 - `BetaManagedAgentsAlwaysAskPolicy object`
84307785
84317786 Tool calls require user confirmation before execution.
84327787
84337788 - `type: "always_ask"`
84347789
8435 - `"always_ask"`
8436
84377790 - `type: optional "read"`
84387791
8439 - `"read"`
8440
84417792### Beta Managed Agents Session Thread Agent
84427793
8443- `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }`
7794- `BetaManagedAgentsSessionThreadAgent object`
84447795
84457796 Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`.
84467797
from line 7805
84547805
84557806 - `type: "url"`
84567807
8457 - `"url"`
8458
84597808 - `url: string`
84607809
84617810 - `model: BetaManagedAgentsModelConfig`
from line 7881
85327881
85337882 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
85347883
8535 - `BetaManagedAgentsEffortLow object { type }`
7884 - `BetaManagedAgentsEffortLow object`
85367885
85377886 Low effort. Favors latency over reasoning depth.
85387887
85397888 - `type: "low"`
85407889
8541 - `"low"`
8542
8543 - `BetaManagedAgentsEffortMedium object { type }`
7890 - `BetaManagedAgentsEffortMedium object`
85447891
85457892 Medium effort. Balances latency and reasoning depth.
85467893
85477894 - `type: "medium"`
85487895
8549 - `"medium"`
8550
8551 - `BetaManagedAgentsEffortHigh object { type }`
7896 - `BetaManagedAgentsEffortHigh object`
85527897
85537898 High effort. Favors reasoning depth.
85547899
85557900 - `type: "high"`
85567901
8557 - `"high"`
8558
8559 - `BetaManagedAgentsEffortXhigh object { type }`
7902 - `BetaManagedAgentsEffortXhigh object`
85607903
85617904 Extra-high effort. Not all models accept this level.
85627905
85637906 - `type: "xhigh"`
85647907
8565 - `"xhigh"`
8566
8567 - `BetaManagedAgentsEffortMax object { type }`
7908 - `BetaManagedAgentsEffortMax object`
85687909
85697910 Maximum effort. Favors reasoning depth over latency.
85707911
85717912 - `type: "max"`
85727913
8573 - `"max"`
8574
85757914 - `inference_geo: optional string`
85767915
85777916 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 7927
85887927
85897928 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
85907929
8591 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
7930 - `BetaManagedAgentsAnthropicSkill object`
85927931
85937932 A resolved Anthropic-managed skill.
85947933
from line 7935
85967935
85977936 - `type: "anthropic"`
85987937
8599 - `"anthropic"`
8600
86017938 - `version: string`
86027939
8603 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
7940 - `BetaManagedAgentsCustomSkill object`
86047941
86057942 A resolved user-created custom skill.
86067943
from line 7945
86087945
86097946 - `type: "custom"`
86107947
8611 - `"custom"`
8612
86137948 - `version: string`
86147949
86157950 - `system: string or null`
86167951
86177952 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
86187953
8619 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
7954 - `BetaManagedAgentsAgentToolset20260401 object`
86207955
86217956 - `configs: array of BetaManagedAgentsAgentToolConfig`
86227957
8623 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
7958 - `BetaManagedAgentsBashToolConfig object`
86247959
86257960 Configuration for the bash tool.
86267961
from line 7963
86287963
86297964 - `name: "bash"`
86307965
8631 - `"bash"`
8632
86337966 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
86347967
86357968 Permission policy for tool execution.
86367969
8637 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
7970 - `BetaManagedAgentsAlwaysAllowPolicy object`
86387971
86397972 Tool calls are automatically approved without user confirmation.
86407973
86417974 - `type: "always_allow"`
86427975
8643 - `"always_allow"`
8644
8645 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
7976 - `BetaManagedAgentsAlwaysAskPolicy object`
86467977
86477978 Tool calls require user confirmation before execution.
86487979
86497980 - `type: "always_ask"`
86507981
8651 - `"always_ask"`
8652
86537982 - `type: "bash"`
86547983
8655 - `"bash"`
8656
8657 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
7984 - `BetaManagedAgentsEditToolConfig object`
86587985
86597986 Configuration for the edit tool.
86607987
from line 7989
86627989
86637990 - `name: "edit"`
86647991
8665 - `"edit"`
8666
86677992 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
86687993
86697994 Permission policy for tool execution.
86707995
8671 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
7996 - `BetaManagedAgentsAlwaysAllowPolicy object`
86727997
86737998 Tool calls are automatically approved without user confirmation.
86747999
8675 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
8000 - `BetaManagedAgentsAlwaysAskPolicy object`
86768001
86778002 Tool calls require user confirmation before execution.
86788003
86798004 - `type: "edit"`
86808005
8681 - `"edit"`
8682
8683 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
8006 - `BetaManagedAgentsReadToolConfig object`
86848007
86858008 Configuration for the read tool.
86868009
from line 8011
86888011
86898012 - `name: "read"`
86908013
8691 - `"read"`
8692
86938014 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
86948015
86958016 Permission policy for tool execution.
86968017
8697 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
8018 - `BetaManagedAgentsAlwaysAllowPolicy object`
86988019
86998020 Tool calls are automatically approved without user confirmation.
87008021
8701 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
8022 - `BetaManagedAgentsAlwaysAskPolicy object`
87028023
87038024 Tool calls require user confirmation before execution.
87048025
87058026 - `type: "read"`
87068027
8707 - `"read"`
8708
8709 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
8028 - `BetaManagedAgentsWriteToolConfig object`
87108029
87118030 Configuration for the write tool.
87128031
from line 8033
87148033
87158034 - `name: "write"`
87168035
8717 - `"write"`
8718
87198036 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
87208037
87218038 Permission policy for tool execution.
87228039
8723 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
8040 - `BetaManagedAgentsAlwaysAllowPolicy object`
87248041
87258042 Tool calls are automatically approved without user confirmation.
87268043
8727 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
8044 - `BetaManagedAgentsAlwaysAskPolicy object`
87288045
87298046 Tool calls require user confirmation before execution.
87308047
87318048 - `type: "write"`
87328049
8733 - `"write"`
8734
8735 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
8050 - `BetaManagedAgentsGlobToolConfig object`
87368051
87378052 Configuration for the glob tool.
87388053
from line 8055
87408055
87418056 - `name: "glob"`
87428057
8743 - `"glob"`
8744
87458058 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
87468059
87478060 Permission policy for tool execution.
87488061
8749 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
8062 - `BetaManagedAgentsAlwaysAllowPolicy object`
87508063
87518064 Tool calls are automatically approved without user confirmation.
87528065
8753 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
8066 - `BetaManagedAgentsAlwaysAskPolicy object`
87548067
87558068 Tool calls require user confirmation before execution.
87568069
87578070 - `type: "glob"`
87588071
8759 - `"glob"`
8760
8761 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
8072 - `BetaManagedAgentsGrepToolConfig object`
87628073
87638074 Configuration for the grep tool.
87648075
from line 8077
87668077
87678078 - `name: "grep"`
87688079
8769 - `"grep"`
8770
87718080 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
87728081
87738082 Permission policy for tool execution.
87748083
8775 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
8084 - `BetaManagedAgentsAlwaysAllowPolicy object`
87768085
87778086 Tool calls are automatically approved without user confirmation.
87788087
8779 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
8088 - `BetaManagedAgentsAlwaysAskPolicy object`
87808089
87818090 Tool calls require user confirmation before execution.
87828091
87838092 - `type: "grep"`
87848093
8785 - `"grep"`
8786
8787 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
8094 - `BetaManagedAgentsWebFetchToolConfig object`
87888095
87898096 Configuration for the web_fetch tool.
87908097
from line 8099
87928099
87938100 - `name: "web_fetch"`
87948101
8795 - `"web_fetch"`
8796
87978102 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
87988103
87998104 Permission policy for tool execution.
88008105
8801 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
8106 - `BetaManagedAgentsAlwaysAllowPolicy object`
88028107
88038108 Tool calls are automatically approved without user confirmation.
88048109
8805 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
8110 - `BetaManagedAgentsAlwaysAskPolicy object`
88068111
88078112 Tool calls require user confirmation before execution.
88088113
88098114 - `type: "web_fetch"`
88108115
8811 - `"web_fetch"`
8812
88138116 - `allowed_domains: optional array of string`
88148117
88158118 - `blocked_domains: optional array of string`
88168119
88178120 - `max_content_tokens: optional number or null`
88188121
8819 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
8122 format: int32
8123
8124 - `BetaManagedAgentsWebSearchToolConfig object`
88208125
88218126 Configuration for the web_search tool.
88228127
from line 8129
88248129
88258130 - `name: "web_search"`
88268131
8827 - `"web_search"`
8828
88298132 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
88308133
88318134 Permission policy for tool execution.
88328135
8833 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
8136 - `BetaManagedAgentsAlwaysAllowPolicy object`
88348137
88358138 Tool calls are automatically approved without user confirmation.
88368139
8837 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
8140 - `BetaManagedAgentsAlwaysAskPolicy object`
88388141
88398142 Tool calls require user confirmation before execution.
88408143
88418144 - `type: "web_search"`
88428145
8843 - `"web_search"`
8844
88458146 - `allowed_domains: optional array of string`
88468147
88478148 - `blocked_domains: optional array of string`
from line 8155
88548155
88558156 Location precision. Only "approximate" is supported.
88568157
8857 - `"approximate"`
8858
88598158 - `city: optional string or null`
88608159
88618160 City name.
88628161
8162 minLength: 1, maxLength: 255
8163
88638164 - `country: optional string or null`
88648165
88658166 Two-letter ISO 3166-1 country code, uppercase.
from line 8169
88688169
88698170 Region or state name.
88708171
8172 minLength: 1, maxLength: 255
8173
88718174 - `timezone: optional string or null`
88728175
88738176 IANA timezone identifier, e.g. "America/Los_Angeles".
88748177
8178 minLength: 1, maxLength: 255
8179
88758180 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
88768181
88778182 Resolved default configuration for agent tools.
from line 8187
88828187
88838188 Permission policy for tool execution.
88848189
8885 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
8190 - `BetaManagedAgentsAlwaysAllowPolicy object`
88868191
88878192 Tool calls are automatically approved without user confirmation.
88888193
8889 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
8194 - `BetaManagedAgentsAlwaysAskPolicy object`
88908195
88918196 Tool calls require user confirmation before execution.
88928197
88938198 - `type: "agent_toolset_20260401"`
88948199
8895 - `"agent_toolset_20260401"`
8896
8897 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
8200 - `BetaManagedAgentsMCPToolset object`
88988201
88998202 - `configs: array of BetaManagedAgentsMCPToolConfig`
89008203
from line 8209
89068209
89078210 Permission policy for tool execution.
89088211
8909 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
8212 - `BetaManagedAgentsAlwaysAllowPolicy object`
89108213
89118214 Tool calls are automatically approved without user confirmation.
89128215
8913 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
8216 - `BetaManagedAgentsAlwaysAskPolicy object`
89148217
89158218 Tool calls require user confirmation before execution.
89168219
from line 8227
89248227
89258228 Permission policy for tool execution.
89268229
8927 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
8230 - `BetaManagedAgentsAlwaysAllowPolicy object`
89288231
89298232 Tool calls are automatically approved without user confirmation.
89308233
8931 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
8234 - `BetaManagedAgentsAlwaysAskPolicy object`
89328235
89338236 Tool calls require user confirmation before execution.
89348237
from line 8239
89368239
89378240 - `type: "mcp_toolset"`
89388241
8939 - `"mcp_toolset"`
8940
8941 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
8242 - `BetaManagedAgentsCustomTool object`
89428243
89438244 A custom tool as returned in API responses.
89448245
from line 8251
89508251
89518252 - `type: "object"`
89528253
8953 - `"object"`
8954
89558254 - `properties: optional map[unknown] or null`
89568255
89578256 - `required: optional array of string or null`
from line 8259
89608259
89618260 - `type: "custom"`
89628261
8963 - `"custom"`
8964
89658262 - `type: "agent"`
89668263
8967 - `"agent"`
8968
89698264 - `version: number`
89708265
8266 format: int32
8267
89718268### Beta Managed Agents Skill Params
89728269
89738270- `BetaManagedAgentsSkillParams = BetaManagedAgentsAnthropicSkillParams or BetaManagedAgentsCustomSkillParams`
89748271
89758272 Skill to load in the session container.
89768273
8977 - `BetaManagedAgentsAnthropicSkillParams object { skill_id, type, version }`
8274 - `BetaManagedAgentsAnthropicSkillParams object`
89788275
89798276 An Anthropic-managed skill.
89808277
from line 8279
89828279
89838280 Identifier of the Anthropic skill (e.g., "xlsx").
89848281
8282 minLength: 1, maxLength: 64
8283
89858284 - `type: "anthropic"`
89868285
8987 - `"anthropic"`
8988
89898286 - `version: optional string or null`
89908287
89918288 Version to pin. Defaults to latest if omitted.
89928289
8993 - `BetaManagedAgentsCustomSkillParams object { skill_id, type, version }`
8290 minLength: 1, maxLength: 64
8291
8292 - `BetaManagedAgentsCustomSkillParams object`
89948293
89958294 A user-created custom skill.
89968295
from line 8297
89988297
89998298 Tagged ID of the custom skill (e.g., "skill_01XJ5...").
90008299
8300 minLength: 1, maxLength: 64
8301
90018302 - `type: "custom"`
90028303
9003 - `"custom"`
9004
90058304 - `version: optional string or null`
90068305
90078306 Version to pin. Defaults to latest if omitted.
90088307
8308 minLength: 1, maxLength: 64
8309
90098310### Beta Managed Agents URL MCP Server Params
90108311
9011- `BetaManagedAgentsURLMCPServerParams object { name, type, url }`
8312- `BetaManagedAgentsURLMCPServerParams object`
90128313
90138314 URL-based MCP server connection.
90148315
from line 8317
90168317
90178318 Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.
90188319
8320 minLength: 1, maxLength: 255
8321
90198322 - `type: "url"`
90208323
9021 - `"url"`
9022
90238324 - `url: string`
90248325
90258326 Endpoint URL for the MCP server.
90268327
8328 maxLength: 2048
8329
90278330### Beta Managed Agents User Location
90288331
9029- `BetaManagedAgentsUserLocation object { type, city, country, 2 more }`
8332- `BetaManagedAgentsUserLocation object`
90308333
90318334 Approximate user location for search result localization.
90328335
from line 8337
90348337
90358338 Location precision. Only "approximate" is supported.
90368339
9037 - `"approximate"`
9038
90398340 - `city: optional string or null`
90408341
90418342 City name.
90428343
8344 minLength: 1, maxLength: 255
8345
90438346 - `country: optional string or null`
90448347
90458348 Two-letter ISO 3166-1 country code, uppercase.
from line 8351
90488351
90498352 Region or state name.
90508353
8354 minLength: 1, maxLength: 255
8355
90518356 - `timezone: optional string or null`
90528357
90538358 IANA timezone identifier, e.g. "America/Los_Angeles".
90548359
8360 minLength: 1, maxLength: 255
8361
90558362### Beta Managed Agents Web Fetch Tool Config
90568363
9057- `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
8364- `BetaManagedAgentsWebFetchToolConfig object`
90588365
90598366 Configuration for the web_fetch tool.
90608367
from line 8369
90628369
90638370 - `name: "web_fetch"`
90648371
9065 - `"web_fetch"`
9066
90678372 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
90688373
90698374 Permission policy for tool execution.
90708375
9071 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
8376 - `BetaManagedAgentsAlwaysAllowPolicy object`
90728377
90738378 Tool calls are automatically approved without user confirmation.
90748379
90758380 - `type: "always_allow"`
90768381
9077 - `"always_allow"`
9078
9079 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
8382 - `BetaManagedAgentsAlwaysAskPolicy object`
90808383
90818384 Tool calls require user confirmation before execution.
90828385
90838386 - `type: "always_ask"`
90848387
9085 - `"always_ask"`
9086
90878388 - `type: "web_fetch"`
90888389
9089 - `"web_fetch"`
9090
90918390 - `allowed_domains: optional array of string`
90928391
90938392 - `blocked_domains: optional array of string`
90948393
90958394 - `max_content_tokens: optional number or null`
90968395
8396 format: int32
8397
90978398### Beta Managed Agents Web Fetch Tool Config Params
90988399
9099- `BetaManagedAgentsWebFetchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }`
8400- `BetaManagedAgentsWebFetchToolConfigParams object`
91008401
91018402 Configuration override for the web_fetch tool.
91028403
from line 8405
91048405
91058406 Must be "web_fetch".
91068407
9107 - `"web_fetch"`
9108
91098408 - `allowed_domains: optional array of string`
91108409
91118410 Only fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
from line 8421
91228421
91238422 Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs.
91248423
8424 format: int32
8425
91258426 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
91268427
91278428 Permission policy for tool execution.
91288429
9129 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
8430 - `BetaManagedAgentsAlwaysAllowPolicy object`
91308431
91318432 Tool calls are automatically approved without user confirmation.
91328433
91338434 - `type: "always_allow"`
91348435
9135 - `"always_allow"`
9136
9137 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
8436 - `BetaManagedAgentsAlwaysAskPolicy object`
91388437
91398438 Tool calls require user confirmation before execution.
91408439
91418440 - `type: "always_ask"`
91428441
9143 - `"always_ask"`
9144
91458442 - `type: optional "web_fetch"`
91468443
9147 - `"web_fetch"`
9148
91498444### Beta Managed Agents Web Search Tool Config
91508445
9151- `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
8446- `BetaManagedAgentsWebSearchToolConfig object`
91528447
91538448 Configuration for the web_search tool.
91548449
from line 8451
91568451
91578452 - `name: "web_search"`
91588453
9159 - `"web_search"`
9160
91618454 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
91628455
91638456 Permission policy for tool execution.
91648457
9165 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
8458 - `BetaManagedAgentsAlwaysAllowPolicy object`
91668459
91678460 Tool calls are automatically approved without user confirmation.
91688461
91698462 - `type: "always_allow"`
91708463
9171 - `"always_allow"`
9172
9173 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
8464 - `BetaManagedAgentsAlwaysAskPolicy object`
91748465
91758466 Tool calls require user confirmation before execution.
91768467
91778468 - `type: "always_ask"`
91788469
9179 - `"always_ask"`
9180
91818470 - `type: "web_search"`
91828471
9183 - `"web_search"`
9184
91858472 - `allowed_domains: optional array of string`
91868473
91878474 - `blocked_domains: optional array of string`
from line 8481
91948481
91958482 Location precision. Only "approximate" is supported.
91968483
9197 - `"approximate"`
9198
91998484 - `city: optional string or null`
92008485
92018486 City name.
92028487
8488 minLength: 1, maxLength: 255
8489
92038490 - `country: optional string or null`
92048491
92058492 Two-letter ISO 3166-1 country code, uppercase.
from line 8495
92088495
92098496 Region or state name.
92108497
8498 minLength: 1, maxLength: 255
8499
92118500 - `timezone: optional string or null`
92128501
92138502 IANA timezone identifier, e.g. "America/Los_Angeles".
92148503
8504 minLength: 1, maxLength: 255
8505
92158506### Beta Managed Agents Web Search Tool Config Params
92168507
9217- `BetaManagedAgentsWebSearchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }`
8508- `BetaManagedAgentsWebSearchToolConfigParams object`
92188509
92198510 Configuration override for the web_search tool.
92208511
from line 8513
92228513
92238514 Must be "web_search".
92248515
9225 - `"web_search"`
9226
92278516 - `allowed_domains: optional array of string`
92288517
92298518 Only return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
from line 8529
92408529
92418530 Permission policy for tool execution.
92428531
9243 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
8532 - `BetaManagedAgentsAlwaysAllowPolicy object`
92448533
92458534 Tool calls are automatically approved without user confirmation.
92468535
92478536 - `type: "always_allow"`
92488537
9249 - `"always_allow"`
9250
9251 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
8538 - `BetaManagedAgentsAlwaysAskPolicy object`
92528539
92538540 Tool calls require user confirmation before execution.
92548541
92558542 - `type: "always_ask"`
92568543
9257 - `"always_ask"`
9258
92598544 - `type: optional "web_search"`
92608545
9261 - `"web_search"`
9262
92638546 - `user_location: optional BetaManagedAgentsUserLocation or null`
92648547
92658548 Approximate user location for search result localization.
from line 8551
92688551
92698552 Location precision. Only "approximate" is supported.
92708553
9271 - `"approximate"`
9272
92738554 - `city: optional string or null`
92748555
92758556 City name.
92768557
8558 minLength: 1, maxLength: 255
8559
92778560 - `country: optional string or null`
92788561
92798562 Two-letter ISO 3166-1 country code, uppercase.
from line 8565
92828565
92838566 Region or state name.
92848567
8568 minLength: 1, maxLength: 255
8569
92858570 - `timezone: optional string or null`
92868571
92878572 IANA timezone identifier, e.g. "America/Los_Angeles".
92888573
8574 minLength: 1, maxLength: 255
8575
92898576### Beta Managed Agents Write Tool Config
92908577
9291- `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
8578- `BetaManagedAgentsWriteToolConfig object`
92928579
92938580 Configuration for the write tool.
92948581
from line 8583
92968583
92978584 - `name: "write"`
92988585
9299 - `"write"`
9300
93018586 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
93028587
93038588 Permission policy for tool execution.
93048589
9305 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
8590 - `BetaManagedAgentsAlwaysAllowPolicy object`
93068591
93078592 Tool calls are automatically approved without user confirmation.
93088593
93098594 - `type: "always_allow"`
93108595
9311 - `"always_allow"`
9312
9313 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
8596 - `BetaManagedAgentsAlwaysAskPolicy object`
93148597
93158598 Tool calls require user confirmation before execution.
93168599
93178600 - `type: "always_ask"`
93188601
9319 - `"always_ask"`
9320
93218602 - `type: "write"`
93228603
9323 - `"write"`
9324
93258604### Beta Managed Agents Write Tool Config Params
93268605
9327- `BetaManagedAgentsWriteToolConfigParams object { name, enabled, permission_policy, type }`
8606- `BetaManagedAgentsWriteToolConfigParams object`
93288607
93298608 Configuration override for the write tool.
93308609
from line 8611
93328611
93338612 Must be "write".
93348613
9335 - `"write"`
9336
93378614 - `enabled: optional boolean or null`
93388615
93398616 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 8619
93428619
93438620 Permission policy for tool execution.
93448621
9345 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
8622 - `BetaManagedAgentsAlwaysAllowPolicy object`
93468623
93478624 Tool calls are automatically approved without user confirmation.
93488625
93498626 - `type: "always_allow"`
93508627
9351 - `"always_allow"`
9352
9353 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
8628 - `BetaManagedAgentsAlwaysAskPolicy object`
93548629
93558630 Tool calls require user confirmation before execution.
93568631
93578632 - `type: "always_ask"`
93588633
9359 - `"always_ask"`
9360
93618634 - `type: optional "write"`
93628635
9363 - `"write"`
9364
9365# Versions
9366
9367## List Agent Versions
9368
9369**get** `/v1/agents/{agent_id}/versions`
8636## Agents › Versions
8637
8638### List Agent Versions
8639
8640**GET** `/v1/agents/{agent_id}/versions`
93708641
93718642List Agent Versions
93728643
9373### Path Parameters
8644#### Path parameters
93748645
93758646- `agent_id: string`
93768647
9377### Query Parameters
8648#### Query parameters
93788649
93798650- `limit: optional number`
93808651
93818652 Maximum results per page. Default 20, maximum 100.
93828653
8654 format: int32
8655
93838656- `page: optional string`
93848657
93858658 Opaque pagination cursor.
93868659
9387### Header Parameters
8660#### Headers
93888661
93898662- `"anthropic-beta": optional array of AnthropicBeta`
93908663
from line 8735
94628735
94638736 - `"mid-conversation-tool-changes-2026-07-01"`
94648737
9465### Returns
8738#### Returns
94668739
94678740- `data: array of BetaManagedAgentsAgent`
94688741
from line 8747
94748747
94758748 A timestamp in RFC 3339 format
94768749
8750 format: date-time
8751
94778752 - `created_at: string`
94788753
94798754 A timestamp in RFC 3339 format
94808755
8756 format: date-time
8757
94818758 - `description: string or null`
94828759
94838760 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
from line 8763
94868763
94878764 - `type: "url"`
94888765
9489 - `"url"`
9490
94918766 - `url: string`
94928767
94938768 - `metadata: map[string]`
from line 8841
95668841
95678842 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
95688843
9569 - `BetaManagedAgentsEffortLow object { type }`
8844 - `BetaManagedAgentsEffortLow object`
95708845
95718846 Low effort. Favors latency over reasoning depth.
95728847
95738848 - `type: "low"`
95748849
9575 - `"low"`
9576
9577 - `BetaManagedAgentsEffortMedium object { type }`
8850 - `BetaManagedAgentsEffortMedium object`
95788851
95798852 Medium effort. Balances latency and reasoning depth.
95808853
95818854 - `type: "medium"`
95828855
9583 - `"medium"`
9584
9585 - `BetaManagedAgentsEffortHigh object { type }`
8856 - `BetaManagedAgentsEffortHigh object`
95868857
95878858 High effort. Favors reasoning depth.
95888859
95898860 - `type: "high"`
95908861
9591 - `"high"`
9592
9593 - `BetaManagedAgentsEffortXhigh object { type }`
8862 - `BetaManagedAgentsEffortXhigh object`
95948863
95958864 Extra-high effort. Not all models accept this level.
95968865
95978866 - `type: "xhigh"`
95988867
9599 - `"xhigh"`
9600
9601 - `BetaManagedAgentsEffortMax object { type }`
8868 - `BetaManagedAgentsEffortMax object`
96028869
96038870 Maximum effort. Favors reasoning depth over latency.
96048871
96058872 - `type: "max"`
96068873
9607 - `"max"`
9608
96098874 - `inference_geo: optional string`
96108875
96118876 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 8891
96268891
96278892 Agents the coordinator may spawn as session threads, each resolved to a specific version.
96288893
9629 - `BetaManagedAgentsAgentReference object { id, type, version }`
8894 - `BetaManagedAgentsAgentReference object`
96308895
96318896 A resolved agent reference with a concrete version.
96328897
from line 8899
96348899
96358900 - `type: "agent"`
96368901
9637 - `"agent"`
9638
96398902 - `version: number`
96408903
9641 - `BetaManagedAgentsAdvisor object { model, type }`
8904 format: int32
8905
8906 - `BetaManagedAgentsAdvisor object`
96428907
96438908 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
96448909
from line 8913
96488913
96498914 - `type: "advisor"`
96508915
9651 - `"advisor"`
9652
96538916 - `type: "coordinator"`
96548917
9655 - `"coordinator"`
9656
96578918 - `name: string`
96588919
96598920 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
96608921
9661 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
8922 - `BetaManagedAgentsAnthropicSkill object`
96628923
96638924 A resolved Anthropic-managed skill.
96648925
from line 8927
96668927
96678928 - `type: "anthropic"`
96688929
9669 - `"anthropic"`
9670
96718930 - `version: string`
96728931
9673 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
8932 - `BetaManagedAgentsCustomSkill object`
96748933
96758934 A resolved user-created custom skill.
96768935
from line 8937
96788937
96798938 - `type: "custom"`
96808939
9681 - `"custom"`
9682
96838940 - `version: string`
96848941
96858942 - `system: string or null`
96868943
96878944 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
96888945
9689 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
8946 - `BetaManagedAgentsAgentToolset20260401 object`
96908947
96918948 - `configs: array of BetaManagedAgentsAgentToolConfig`
96928949
9693 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
8950 - `BetaManagedAgentsBashToolConfig object`
96948951
96958952 Configuration for the bash tool.
96968953
from line 8955
96988955
96998956 - `name: "bash"`
97008957
9701 - `"bash"`
9702
97038958 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
97048959
97058960 Permission policy for tool execution.
97068961
9707 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
8962 - `BetaManagedAgentsAlwaysAllowPolicy object`
97088963
97098964 Tool calls are automatically approved without user confirmation.
97108965
97118966 - `type: "always_allow"`
97128967
9713 - `"always_allow"`
9714
9715 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
8968 - `BetaManagedAgentsAlwaysAskPolicy object`
97168969
97178970 Tool calls require user confirmation before execution.
97188971
97198972 - `type: "always_ask"`
97208973
9721 - `"always_ask"`
9722
97238974 - `type: "bash"`
97248975
9725 - `"bash"`
9726
9727 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
8976 - `BetaManagedAgentsEditToolConfig object`
97288977
97298978 Configuration for the edit tool.
97308979
from line 8981
97328981
97338982 - `name: "edit"`
97348983
9735 - `"edit"`
9736
97378984 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
97388985
97398986 Permission policy for tool execution.
97408987
9741 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
8988 - `BetaManagedAgentsAlwaysAllowPolicy object`
97428989
97438990 Tool calls are automatically approved without user confirmation.
97448991
9745 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
8992 - `BetaManagedAgentsAlwaysAskPolicy object`
97468993
97478994 Tool calls require user confirmation before execution.
97488995
97498996 - `type: "edit"`
97508997
9751 - `"edit"`
9752
9753 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
8998 - `BetaManagedAgentsReadToolConfig object`
97548999
97559000 Configuration for the read tool.
97569001
from line 9003
97589003
97599004 - `name: "read"`
97609005
9761 - `"read"`
9762
97639006 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
97649007
97659008 Permission policy for tool execution.
97669009
9767 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
9010 - `BetaManagedAgentsAlwaysAllowPolicy object`
97689011
97699012 Tool calls are automatically approved without user confirmation.
97709013
9771 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
9014 - `BetaManagedAgentsAlwaysAskPolicy object`
97729015
97739016 Tool calls require user confirmation before execution.
97749017
97759018 - `type: "read"`
97769019
9777 - `"read"`
9778
9779 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
9020 - `BetaManagedAgentsWriteToolConfig object`
97809021
97819022 Configuration for the write tool.
97829023
from line 9025
97849025
97859026 - `name: "write"`
97869027
9787 - `"write"`
9788
97899028 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
97909029
97919030 Permission policy for tool execution.
97929031
9793 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
9032 - `BetaManagedAgentsAlwaysAllowPolicy object`
97949033
97959034 Tool calls are automatically approved without user confirmation.
97969035
9797 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
9036 - `BetaManagedAgentsAlwaysAskPolicy object`
97989037
97999038 Tool calls require user confirmation before execution.
98009039
98019040 - `type: "write"`
98029041
9803 - `"write"`
9804
9805 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
9042 - `BetaManagedAgentsGlobToolConfig object`
98069043
98079044 Configuration for the glob tool.
98089045
from line 9047
98109047
98119048 - `name: "glob"`
98129049
9813 - `"glob"`
9814
98159050 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
98169051
98179052 Permission policy for tool execution.
98189053
9819 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
9054 - `BetaManagedAgentsAlwaysAllowPolicy object`
98209055
98219056 Tool calls are automatically approved without user confirmation.
98229057
9823 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
9058 - `BetaManagedAgentsAlwaysAskPolicy object`
98249059
98259060 Tool calls require user confirmation before execution.
98269061
98279062 - `type: "glob"`
98289063
9829 - `"glob"`
9830
9831 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
9064 - `BetaManagedAgentsGrepToolConfig object`
98329065
98339066 Configuration for the grep tool.
98349067
from line 9069
98369069
98379070 - `name: "grep"`
98389071
9839 - `"grep"`
9840
98419072 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
98429073
98439074 Permission policy for tool execution.
98449075
9845 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
9076 - `BetaManagedAgentsAlwaysAllowPolicy object`
98469077
98479078 Tool calls are automatically approved without user confirmation.
98489079
9849 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
9080 - `BetaManagedAgentsAlwaysAskPolicy object`
98509081
98519082 Tool calls require user confirmation before execution.
98529083
98539084 - `type: "grep"`
98549085
9855 - `"grep"`
9856
9857 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
9086 - `BetaManagedAgentsWebFetchToolConfig object`
98589087
98599088 Configuration for the web_fetch tool.
98609089
from line 9091
98629091
98639092 - `name: "web_fetch"`
98649093
9865 - `"web_fetch"`
9866
98679094 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
98689095
98699096 Permission policy for tool execution.
98709097
9871 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
9098 - `BetaManagedAgentsAlwaysAllowPolicy object`
98729099
98739100 Tool calls are automatically approved without user confirmation.
98749101
9875 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
9102 - `BetaManagedAgentsAlwaysAskPolicy object`
98769103
98779104 Tool calls require user confirmation before execution.
98789105
98799106 - `type: "web_fetch"`
98809107
9881 - `"web_fetch"`
9882
98839108 - `allowed_domains: optional array of string`
98849109
98859110 - `blocked_domains: optional array of string`
98869111
98879112 - `max_content_tokens: optional number or null`
98889113
9889 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
9114 format: int32
9115
9116 - `BetaManagedAgentsWebSearchToolConfig object`
98909117
98919118 Configuration for the web_search tool.
98929119
from line 9121
98949121
98959122 - `name: "web_search"`
98969123
9897 - `"web_search"`
9898
98999124 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
99009125
99019126 Permission policy for tool execution.
99029127
9903 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
9128 - `BetaManagedAgentsAlwaysAllowPolicy object`
99049129
99059130 Tool calls are automatically approved without user confirmation.
99069131
9907 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
9132 - `BetaManagedAgentsAlwaysAskPolicy object`
99089133
99099134 Tool calls require user confirmation before execution.
99109135
99119136 - `type: "web_search"`
99129137
9913 - `"web_search"`
9914
99159138 - `allowed_domains: optional array of string`
99169139
99179140 - `blocked_domains: optional array of string`
from line 9147
99249147
99259148 Location precision. Only "approximate" is supported.
99269149
9927 - `"approximate"`
9928
99299150 - `city: optional string or null`
99309151
99319152 City name.
99329153
9154 minLength: 1, maxLength: 255
9155
99339156 - `country: optional string or null`
99349157
99359158 Two-letter ISO 3166-1 country code, uppercase.
from line 9161
99389161
99399162 Region or state name.
99409163
9164 minLength: 1, maxLength: 255
9165
99419166 - `timezone: optional string or null`
99429167
99439168 IANA timezone identifier, e.g. "America/Los_Angeles".
99449169
9170 minLength: 1, maxLength: 255
9171
99459172 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
99469173
99479174 Resolved default configuration for agent tools.
from line 9179
99529179
99539180 Permission policy for tool execution.
99549181
9955 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
9182 - `BetaManagedAgentsAlwaysAllowPolicy object`
99569183
99579184 Tool calls are automatically approved without user confirmation.
99589185
9959 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
9186 - `BetaManagedAgentsAlwaysAskPolicy object`
99609187
99619188 Tool calls require user confirmation before execution.
99629189
99639190 - `type: "agent_toolset_20260401"`
99649191
9965 - `"agent_toolset_20260401"`
9966
9967 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
9192 - `BetaManagedAgentsMCPToolset object`
99689193
99699194 - `configs: array of BetaManagedAgentsMCPToolConfig`
99709195
from line 9201
99769201
99779202 Permission policy for tool execution.
99789203
9979 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
9204 - `BetaManagedAgentsAlwaysAllowPolicy object`
99809205
99819206 Tool calls are automatically approved without user confirmation.
99829207
9983 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
9208 - `BetaManagedAgentsAlwaysAskPolicy object`
99849209
99859210 Tool calls require user confirmation before execution.
99869211
from line 9219
99949219
99959220 Permission policy for tool execution.
99969221
9997 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
9222 - `BetaManagedAgentsAlwaysAllowPolicy object`
99989223
99999224 Tool calls are automatically approved without user confirmation.
100009225
10001 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
9226 - `BetaManagedAgentsAlwaysAskPolicy object`
100029227
100039228 Tool calls require user confirmation before execution.
100049229
from line 9231
100069231
100079232 - `type: "mcp_toolset"`
100089233
10009 - `"mcp_toolset"`
10010
10011 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
9234 - `BetaManagedAgentsCustomTool object`
100129235
100139236 A custom tool as returned in API responses.
100149237
from line 9243
100209243
100219244 - `type: "object"`
100229245
10023 - `"object"`
10024
100259246 - `properties: optional map[unknown] or null`
100269247
100279248 - `required: optional array of string or null`
from line 9251
100309251
100319252 - `type: "custom"`
100329253
10033 - `"custom"`
10034
100359254 - `type: "agent"`
100369255
10037 - `"agent"`
10038
100399256 - `updated_at: string`
100409257
100419258 A timestamp in RFC 3339 format
100429259
9260 format: date-time
9261
100439262 - `version: number`
100449263
100459264 The agent's current version. Starts at 1 and increments when the agent is modified.
100469265
9266 format: int32
9267
100479268- `next_page: optional string or null`
100489269
100499270 Opaque cursor for the next page. Null when no more results.
100509271
10051### Example
10052
10053```http
9272#### Example
9273
9274```bash
100549275curl https://api.anthropic.com/v1/agents/$AGENT_ID/versions \
100559276 -H 'anthropic-version: 2023-06-01' \
100569277 -H 'anthropic-beta: managed-agents-2026-04-01' \
100579278 -H "X-Api-Key: $ANTHROPIC_API_KEY"
100589279```
100599280
10060#### Response
9281##### Response (200)
100619282
100629283```json
100639284{
100649285
api/beta/agents/archive Changed · +72 / -129 lines
# Archive Agent ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Archive Agent ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Archive Agent
3url: https://platform.claude.com/docs/en/api/beta/agents/archive
4---
1# Archive Agent
52
6## Archive Agent
3**POST** `/v1/agents/{agent_id}/archive`
74
8**post** `/v1/agents/{agent_id}/archive`
9
105Archive Agent
116
12### Path Parameters
7## Path parameters
138
149- `agent_id: string`
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Returns
89## Returns
9590
96- `BetaManagedAgentsAgent object { id, archived_at, created_at, 12 more }`
91- `BetaManagedAgentsAgent object`
9792
9893 A Managed Agents `agent`.
9994
from line 98
10398
10499 A timestamp in RFC 3339 format
105100
101 format: date-time
102
106103 - `created_at: string`
107104
108105 A timestamp in RFC 3339 format
109106
107 format: date-time
108
110109 - `description: string or null`
111110
112111 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
from line 114
115114
116115 - `type: "url"`
117116
118 - `"url"`
119
120117 - `url: string`
121118
122119 - `metadata: map[string]`
from line 192
195192
196193 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
197194
198 - `BetaManagedAgentsEffortLow object { type }`
195 - `BetaManagedAgentsEffortLow object`
199196
200197 Low effort. Favors latency over reasoning depth.
201198
202199 - `type: "low"`
203200
204 - `"low"`
201 - `BetaManagedAgentsEffortMedium object`
205202
206 - `BetaManagedAgentsEffortMedium object { type }`
207
208203 Medium effort. Balances latency and reasoning depth.
209204
210205 - `type: "medium"`
211206
212 - `"medium"`
207 - `BetaManagedAgentsEffortHigh object`
213208
214 - `BetaManagedAgentsEffortHigh object { type }`
215
216209 High effort. Favors reasoning depth.
217210
218211 - `type: "high"`
219212
220 - `"high"`
213 - `BetaManagedAgentsEffortXhigh object`
221214
222 - `BetaManagedAgentsEffortXhigh object { type }`
223
224215 Extra-high effort. Not all models accept this level.
225216
226217 - `type: "xhigh"`
227218
228 - `"xhigh"`
219 - `BetaManagedAgentsEffortMax object`
229220
230 - `BetaManagedAgentsEffortMax object { type }`
231
232221 Maximum effort. Favors reasoning depth over latency.
233222
234223 - `type: "max"`
235224
236 - `"max"`
237
238225 - `inference_geo: optional string`
239226
240227 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 242
255242
256243 Agents the coordinator may spawn as session threads, each resolved to a specific version.
257244
258 - `BetaManagedAgentsAgentReference object { id, type, version }`
245 - `BetaManagedAgentsAgentReference object`
259246
260247 A resolved agent reference with a concrete version.
261248
from line 250
263250
264251 - `type: "agent"`
265252
266 - `"agent"`
267
268253 - `version: number`
269254
270 - `BetaManagedAgentsAdvisor object { model, type }`
255 format: int32
271256
257 - `BetaManagedAgentsAdvisor object`
258
272259 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
273260
274261 - `model: string`
from line 264
277264
278265 - `type: "advisor"`
279266
280 - `"advisor"`
281
282267 - `type: "coordinator"`
283268
284 - `"coordinator"`
285
286269 - `name: string`
287270
288271 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
289272
290 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
273 - `BetaManagedAgentsAnthropicSkill object`
291274
292275 A resolved Anthropic-managed skill.
293276
from line 278
295278
296279 - `type: "anthropic"`
297280
298 - `"anthropic"`
299
300281 - `version: string`
301282
302 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
283 - `BetaManagedAgentsCustomSkill object`
303284
304285 A resolved user-created custom skill.
305286
from line 288
307288
308289 - `type: "custom"`
309290
310 - `"custom"`
311
312291 - `version: string`
313292
314293 - `system: string or null`
from line 294
315294
316295 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
317296
318 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
297 - `BetaManagedAgentsAgentToolset20260401 object`
319298
320299 - `configs: array of BetaManagedAgentsAgentToolConfig`
321300
322 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
301 - `BetaManagedAgentsBashToolConfig object`
323302
324303 Configuration for the bash tool.
325304
from line 306
327306
328307 - `name: "bash"`
329308
330 - `"bash"`
331
332309 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
333310
334311 Permission policy for tool execution.
335312
336 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
313 - `BetaManagedAgentsAlwaysAllowPolicy object`
337314
338315 Tool calls are automatically approved without user confirmation.
339316
340317 - `type: "always_allow"`
341318
342 - `"always_allow"`
319 - `BetaManagedAgentsAlwaysAskPolicy object`
343320
344 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
345
346321 Tool calls require user confirmation before execution.
347322
348323 - `type: "always_ask"`
349324
350 - `"always_ask"`
351
352325 - `type: "bash"`
353326
354 - `"bash"`
327 - `BetaManagedAgentsEditToolConfig object`
355328
356 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
357
358329 Configuration for the edit tool.
359330
360331 - `enabled: boolean`
from line 332
361332
362333 - `name: "edit"`
363334
364 - `"edit"`
365
366335 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
367336
368337 Permission policy for tool execution.
369338
370 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
339 - `BetaManagedAgentsAlwaysAllowPolicy object`
371340
372341 Tool calls are automatically approved without user confirmation.
373342
374 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
343 - `BetaManagedAgentsAlwaysAskPolicy object`
375344
376345 Tool calls require user confirmation before execution.
377346
378347 - `type: "edit"`
379348
380 - `"edit"`
349 - `BetaManagedAgentsReadToolConfig object`
381350
382 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
383
384351 Configuration for the read tool.
385352
386353 - `enabled: boolean`
from line 354
387354
388355 - `name: "read"`
389356
390 - `"read"`
391
392357 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
393358
394359 Permission policy for tool execution.
395360
396 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
361 - `BetaManagedAgentsAlwaysAllowPolicy object`
397362
398363 Tool calls are automatically approved without user confirmation.
399364
400 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
365 - `BetaManagedAgentsAlwaysAskPolicy object`
401366
402367 Tool calls require user confirmation before execution.
403368
404369 - `type: "read"`
405370
406 - `"read"`
371 - `BetaManagedAgentsWriteToolConfig object`
407372
408 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
409
410373 Configuration for the write tool.
411374
412375 - `enabled: boolean`
from line 376
413376
414377 - `name: "write"`
415378
416 - `"write"`
417
418379 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
419380
420381 Permission policy for tool execution.
421382
422 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
383 - `BetaManagedAgentsAlwaysAllowPolicy object`
423384
424385 Tool calls are automatically approved without user confirmation.
425386
426 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
387 - `BetaManagedAgentsAlwaysAskPolicy object`
427388
428389 Tool calls require user confirmation before execution.
429390
430391 - `type: "write"`
431392
432 - `"write"`
393 - `BetaManagedAgentsGlobToolConfig object`
433394
434 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
435
436395 Configuration for the glob tool.
437396
438397 - `enabled: boolean`
from line 398
439398
440399 - `name: "glob"`
441400
442 - `"glob"`
443
444401 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
445402
446403 Permission policy for tool execution.
447404
448 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
405 - `BetaManagedAgentsAlwaysAllowPolicy object`
449406
450407 Tool calls are automatically approved without user confirmation.
451408
452 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
409 - `BetaManagedAgentsAlwaysAskPolicy object`
453410
454411 Tool calls require user confirmation before execution.
455412
456413 - `type: "glob"`
457414
458 - `"glob"`
415 - `BetaManagedAgentsGrepToolConfig object`
459416
460 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
461
462417 Configuration for the grep tool.
463418
464419 - `enabled: boolean`
from line 420
465420
466421 - `name: "grep"`
467422
468 - `"grep"`
469
470423 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
471424
472425 Permission policy for tool execution.
473426
474 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
427 - `BetaManagedAgentsAlwaysAllowPolicy object`
475428
476429 Tool calls are automatically approved without user confirmation.
477430
478 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
431 - `BetaManagedAgentsAlwaysAskPolicy object`
479432
480433 Tool calls require user confirmation before execution.
481434
482435 - `type: "grep"`
483436
484 - `"grep"`
437 - `BetaManagedAgentsWebFetchToolConfig object`
485438
486 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
487
488439 Configuration for the web_fetch tool.
489440
490441 - `enabled: boolean`
from line 442
491442
492443 - `name: "web_fetch"`
493444
494 - `"web_fetch"`
495
496445 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
497446
498447 Permission policy for tool execution.
499448
500 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
449 - `BetaManagedAgentsAlwaysAllowPolicy object`
501450
502451 Tool calls are automatically approved without user confirmation.
503452
504 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
453 - `BetaManagedAgentsAlwaysAskPolicy object`
505454
506455 Tool calls require user confirmation before execution.
507456
508457 - `type: "web_fetch"`
509458
510 - `"web_fetch"`
511
512459 - `allowed_domains: optional array of string`
513460
514461 - `blocked_domains: optional array of string`
from line 462
515462
516463 - `max_content_tokens: optional number or null`
517464
518 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
465 format: int32
519466
467 - `BetaManagedAgentsWebSearchToolConfig object`
468
520469 Configuration for the web_search tool.
521470
522471 - `enabled: boolean`
from line 472
523472
524473 - `name: "web_search"`
525474
526 - `"web_search"`
527
528475 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
529476
530477 Permission policy for tool execution.
531478
532 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
479 - `BetaManagedAgentsAlwaysAllowPolicy object`
533480
534481 Tool calls are automatically approved without user confirmation.
535482
536 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
483 - `BetaManagedAgentsAlwaysAskPolicy object`
537484
538485 Tool calls require user confirmation before execution.
539486
540487 - `type: "web_search"`
541488
542 - `"web_search"`
543
544489 - `allowed_domains: optional array of string`
545490
546491 - `blocked_domains: optional array of string`
from line 498
553498
554499 Location precision. Only "approximate" is supported.
555500
556 - `"approximate"`
557
558501 - `city: optional string or null`
559502
560503 City name.
561504
505 minLength: 1, maxLength: 255
506
562507 - `country: optional string or null`
563508
564509 Two-letter ISO 3166-1 country code, uppercase.
from line 512
567512
568513 Region or state name.
569514
515 minLength: 1, maxLength: 255
516
570517 - `timezone: optional string or null`
571518
572519 IANA timezone identifier, e.g. "America/Los_Angeles".
573520
521 minLength: 1, maxLength: 255
522
574523 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
575524
576525 Resolved default configuration for agent tools.
from line 530
581530
582531 Permission policy for tool execution.
583532
584 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
533 - `BetaManagedAgentsAlwaysAllowPolicy object`
585534
586535 Tool calls are automatically approved without user confirmation.
587536
588 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
537 - `BetaManagedAgentsAlwaysAskPolicy object`
589538
590539 Tool calls require user confirmation before execution.
591540
592541 - `type: "agent_toolset_20260401"`
593542
594 - `"agent_toolset_20260401"`
543 - `BetaManagedAgentsMCPToolset object`
595544
596 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
597
598545 - `configs: array of BetaManagedAgentsMCPToolConfig`
599546
600547 - `enabled: boolean`
from line 552
605552
606553 Permission policy for tool execution.
607554
608 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
555 - `BetaManagedAgentsAlwaysAllowPolicy object`
609556
610557 Tool calls are automatically approved without user confirmation.
611558
612 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
559 - `BetaManagedAgentsAlwaysAskPolicy object`
613560
614561 Tool calls require user confirmation before execution.
615562
from line 570
623570
624571 Permission policy for tool execution.
625572
626 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
573 - `BetaManagedAgentsAlwaysAllowPolicy object`
627574
628575 Tool calls are automatically approved without user confirmation.
629576
630 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
577 - `BetaManagedAgentsAlwaysAskPolicy object`
631578
632579 Tool calls require user confirmation before execution.
633580
from line 582
635582
636583 - `type: "mcp_toolset"`
637584
638 - `"mcp_toolset"`
585 - `BetaManagedAgentsCustomTool object`
639586
640 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
641
642587 A custom tool as returned in API responses.
643588
644589 - `description: string`
from line 594
649594
650595 - `type: "object"`
651596
652 - `"object"`
653
654597 - `properties: optional map[unknown] or null`
655598
656599 - `required: optional array of string or null`
from line 602
659602
660603 - `type: "custom"`
661604
662 - `"custom"`
663
664605 - `type: "agent"`
665606
666 - `"agent"`
667
668607 - `updated_at: string`
669608
670609 A timestamp in RFC 3339 format
671610
611 format: date-time
612
672613 - `version: number`
673614
674615 The agent's current version. Starts at 1 and increments when the agent is modified.
675616
676### Example
617 format: int32
677618
678```http
619## Example
620
621```bash
679622curl https://api.anthropic.com/v1/agents/$AGENT_ID/archive \
680623 -X POST \
681624 -H 'anthropic-version: 2023-06-01' \
from line 626
683626 -H "X-Api-Key: $ANTHROPIC_API_KEY"
684627```
685628
686#### Response
629### Response (200)
687630
688631```json
689632{
api/beta/agents/create Changed · +156 / -243 lines
# Create Agent ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Create Agent ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Create Agent
3url: https://platform.claude.com/docs/en/api/beta/agents/create
4---
1# Create Agent
52
6## Create Agent
3**POST** `/v1/agents`
74
8**post** `/v1/agents`
9
105Create Agent
116
12### Header Parameters
7## Headers
138
149- `"anthropic-beta": optional array of AnthropicBeta`
1510
from line 82
8782
8883 - `"mid-conversation-tool-changes-2026-07-01"`
8984
90### Body Parameters
85## Body parameters
9186
9287- `model: BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams`
9388
from line 154
159154
160155 - `string`
161156
162 - `BetaManagedAgentsModelConfigParams object { id, effort, inference_geo, speed }`
157 - `BetaManagedAgentsModelConfigParams object`
163158
164159 An object that defines additional configuration control over model use
165160
from line 182
187182
188183 - `"max"`
189184
190 - `BetaManagedAgentsEffortLow object { type }`
185 - `BetaManagedAgentsEffortLow object`
191186
192187 Low effort. Favors latency over reasoning depth.
193188
194189 - `type: "low"`
195190
196 - `"low"`
191 - `BetaManagedAgentsEffortMedium object`
197192
198 - `BetaManagedAgentsEffortMedium object { type }`
199
200193 Medium effort. Balances latency and reasoning depth.
201194
202195 - `type: "medium"`
203196
204 - `"medium"`
197 - `BetaManagedAgentsEffortHigh object`
205198
206 - `BetaManagedAgentsEffortHigh object { type }`
207
208199 High effort. Favors reasoning depth.
209200
210201 - `type: "high"`
211202
212 - `"high"`
203 - `BetaManagedAgentsEffortXhigh object`
213204
214 - `BetaManagedAgentsEffortXhigh object { type }`
215
216205 Extra-high effort. Not all models accept this level.
217206
218207 - `type: "xhigh"`
219208
220 - `"xhigh"`
209 - `BetaManagedAgentsEffortMax object`
221210
222 - `BetaManagedAgentsEffortMax object { type }`
223
224211 Maximum effort. Favors reasoning depth over latency.
225212
226213 - `type: "max"`
227214
228 - `"max"`
229
230215 - `inference_geo: optional string or null`
231216
232217 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. On update, `model` is whole-object replacement — omitting inference_geo clears it.
from line 228
243228
244229 Human-readable name for the agent.
245230
231 minLength: 1, maxLength: 256
232
246233- `description: optional string or null`
247234
248235 Description of what the agent does.
249236
237 maxLength: 2048
238
250239- `mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams`
251240
252241 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).
from line 244
255244
256245 Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.
257246
247 minLength: 1, maxLength: 255
248
258249 - `type: "url"`
259250
260 - `"url"`
261
262251 - `url: string`
263252
264253 Endpoint URL for the MCP server.
265254
255 maxLength: 2048
256
266257- `metadata: optional map[string]`
267258
268259 Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.
from line 268
277268
278269 - `string`
279270
280 - `BetaManagedAgentsAgentParams object { id, type, version }`
271 - `BetaManagedAgentsAgentParams object`
281272
282273 Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version
283274
from line 276
285276
286277 The `agent` ID.
287278
279 minLength: 1, maxLength: 128
280
288281 - `type: "agent"`
289282
290 - `"agent"`
291
292283 - `version: optional number`
293284
294285 The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.
295286
296 - `BetaManagedAgentsMultiagentSelfParams object { type }`
287 format: int32
297288
289 - `BetaManagedAgentsMultiagentSelfParams object`
290
298291 Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference.
299292
300293 - `type: "self"`
301294
302 - `"self"`
295 - `BetaManagedAgentsAdvisorParams object`
303296
304 - `BetaManagedAgentsAdvisorParams object { model, type }`
305
306297 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`.
307298
308299 - `model: string`
from line 300
309300
310301 A Claude model id. The model must be permitted as an advisor for this agent's model — see the sessions/threads/advisor spec.
311302
303 minLength: 1, maxLength: 256
304
312305 - `type: "advisor"`
313306
314 - `"advisor"`
315
316307 - `type: "coordinator"`
317308
318 - `"coordinator"`
319
320309- `skills: optional array of BetaManagedAgentsSkillParams`
321310
322311 Skills available to the agent.
323312
324 - `BetaManagedAgentsAnthropicSkillParams object { skill_id, type, version }`
313 - `BetaManagedAgentsAnthropicSkillParams object`
325314
326315 An Anthropic-managed skill.
327316
from line 318
329318
330319 Identifier of the Anthropic skill (e.g., "xlsx").
331320
321 minLength: 1, maxLength: 64
322
332323 - `type: "anthropic"`
333324
334 - `"anthropic"`
335
336325 - `version: optional string or null`
337326
338327 Version to pin. Defaults to latest if omitted.
339328
340 - `BetaManagedAgentsCustomSkillParams object { skill_id, type, version }`
329 minLength: 1, maxLength: 64
341330
331 - `BetaManagedAgentsCustomSkillParams object`
332
342333 A user-created custom skill.
343334
344335 - `skill_id: string`
from line 336
345336
346337 Tagged ID of the custom skill (e.g., "skill_01XJ5...").
347338
339 minLength: 1, maxLength: 64
340
348341 - `type: "custom"`
349342
350 - `"custom"`
351
352343 - `version: optional string or null`
353344
354345 Version to pin. Defaults to latest if omitted.
355346
347 minLength: 1, maxLength: 64
348
356349- `system: optional string or null`
357350
358351 System prompt for the agent.
359352
353 maxLength: 100000
354
360355- `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams`
361356
362357 Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed.
363358
364 - `BetaManagedAgentsAgentToolset20260401Params object { type, configs, default_config }`
359 - `BetaManagedAgentsAgentToolset20260401Params object`
365360
366361 Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.
367362
368363 - `type: "agent_toolset_20260401"`
369364
370 - `"agent_toolset_20260401"`
371
372365 - `configs: optional array of BetaManagedAgentsAgentToolConfigParams`
373366
374367 Per-tool configuration overrides.
375368
376 - `BetaManagedAgentsBashToolConfigParams object { name, enabled, permission_policy, type }`
369 - `BetaManagedAgentsBashToolConfigParams object`
377370
378371 Configuration override for the bash tool.
379372
from line 374
381374
382375 Must be "bash".
383376
384 - `"bash"`
385
386377 - `enabled: optional boolean or null`
387378
388379 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 382
391382
392383 Permission policy for tool execution.
393384
394 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
385 - `BetaManagedAgentsAlwaysAllowPolicy object`
395386
396387 Tool calls are automatically approved without user confirmation.
397388
398389 - `type: "always_allow"`
399390
400 - `"always_allow"`
391 - `BetaManagedAgentsAlwaysAskPolicy object`
401392
402 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
403
404393 Tool calls require user confirmation before execution.
405394
406395 - `type: "always_ask"`
407396
408 - `"always_ask"`
409
410397 - `type: optional "bash"`
411398
412 - `"bash"`
399 - `BetaManagedAgentsEditToolConfigParams object`
413400
414 - `BetaManagedAgentsEditToolConfigParams object { name, enabled, permission_policy, type }`
415
416401 Configuration override for the edit tool.
417402
418403 - `name: "edit"`
from line 404
419404
420405 Must be "edit".
421406
422 - `"edit"`
423
424407 - `enabled: optional boolean or null`
425408
426409 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 412
429412
430413 Permission policy for tool execution.
431414
432 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
415 - `BetaManagedAgentsAlwaysAllowPolicy object`
433416
434417 Tool calls are automatically approved without user confirmation.
435418
436 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
419 - `BetaManagedAgentsAlwaysAskPolicy object`
437420
438421 Tool calls require user confirmation before execution.
439422
440423 - `type: optional "edit"`
441424
442 - `"edit"`
425 - `BetaManagedAgentsReadToolConfigParams object`
443426
444 - `BetaManagedAgentsReadToolConfigParams object { name, enabled, permission_policy, type }`
445
446427 Configuration override for the read tool.
447428
448429 - `name: "read"`
from line 430
449430
450431 Must be "read".
451432
452 - `"read"`
453
454433 - `enabled: optional boolean or null`
455434
456435 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 438
459438
460439 Permission policy for tool execution.
461440
462 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
441 - `BetaManagedAgentsAlwaysAllowPolicy object`
463442
464443 Tool calls are automatically approved without user confirmation.
465444
466 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
445 - `BetaManagedAgentsAlwaysAskPolicy object`
467446
468447 Tool calls require user confirmation before execution.
469448
470449 - `type: optional "read"`
471450
472 - `"read"`
451 - `BetaManagedAgentsWriteToolConfigParams object`
473452
474 - `BetaManagedAgentsWriteToolConfigParams object { name, enabled, permission_policy, type }`
475
476453 Configuration override for the write tool.
477454
478455 - `name: "write"`
from line 456
479456
480457 Must be "write".
481458
482 - `"write"`
483
484459 - `enabled: optional boolean or null`
485460
486461 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 464
489464
490465 Permission policy for tool execution.
491466
492 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
467 - `BetaManagedAgentsAlwaysAllowPolicy object`
493468
494469 Tool calls are automatically approved without user confirmation.
495470
496 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
471 - `BetaManagedAgentsAlwaysAskPolicy object`
497472
498473 Tool calls require user confirmation before execution.
499474
500475 - `type: optional "write"`
501476
502 - `"write"`
477 - `BetaManagedAgentsGlobToolConfigParams object`
503478
504 - `BetaManagedAgentsGlobToolConfigParams object { name, enabled, permission_policy, type }`
505
506479 Configuration override for the glob tool.
507480
508481 - `name: "glob"`
from line 482
509482
510483 Must be "glob".
511484
512 - `"glob"`
513
514485 - `enabled: optional boolean or null`
515486
516487 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 490
519490
520491 Permission policy for tool execution.
521492
522 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
493 - `BetaManagedAgentsAlwaysAllowPolicy object`
523494
524495 Tool calls are automatically approved without user confirmation.
525496
526 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
497 - `BetaManagedAgentsAlwaysAskPolicy object`
527498
528499 Tool calls require user confirmation before execution.
529500
530501 - `type: optional "glob"`
531502
532 - `"glob"`
503 - `BetaManagedAgentsGrepToolConfigParams object`
533504
534 - `BetaManagedAgentsGrepToolConfigParams object { name, enabled, permission_policy, type }`
535
536505 Configuration override for the grep tool.
537506
538507 - `name: "grep"`
from line 508
539508
540509 Must be "grep".
541510
542 - `"grep"`
543
544511 - `enabled: optional boolean or null`
545512
546513 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 516
549516
550517 Permission policy for tool execution.
551518
552 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
519 - `BetaManagedAgentsAlwaysAllowPolicy object`
553520
554521 Tool calls are automatically approved without user confirmation.
555522
556 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
523 - `BetaManagedAgentsAlwaysAskPolicy object`
557524
558525 Tool calls require user confirmation before execution.
559526
560527 - `type: optional "grep"`
561528
562 - `"grep"`
529 - `BetaManagedAgentsWebFetchToolConfigParams object`
563530
564 - `BetaManagedAgentsWebFetchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }`
565
566531 Configuration override for the web_fetch tool.
567532
568533 - `name: "web_fetch"`
from line 534
569534
570535 Must be "web_fetch".
571536
572 - `"web_fetch"`
573
574537 - `allowed_domains: optional array of string`
575538
576539 Only fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
from line 550
587550
588551 Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs.
589552
553 format: int32
554
590555 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
591556
592557 Permission policy for tool execution.
593558
594 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
559 - `BetaManagedAgentsAlwaysAllowPolicy object`
595560
596561 Tool calls are automatically approved without user confirmation.
597562
598 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
563 - `BetaManagedAgentsAlwaysAskPolicy object`
599564
600565 Tool calls require user confirmation before execution.
601566
602567 - `type: optional "web_fetch"`
603568
604 - `"web_fetch"`
569 - `BetaManagedAgentsWebSearchToolConfigParams object`
605570
606 - `BetaManagedAgentsWebSearchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }`
607
608571 Configuration override for the web_search tool.
609572
610573 - `name: "web_search"`
from line 574
611574
612575 Must be "web_search".
613576
614 - `"web_search"`
615
616577 - `allowed_domains: optional array of string`
617578
618579 Only return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
from line 590
629590
630591 Permission policy for tool execution.
631592
632 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
593 - `BetaManagedAgentsAlwaysAllowPolicy object`
633594
634595 Tool calls are automatically approved without user confirmation.
635596
636 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
597 - `BetaManagedAgentsAlwaysAskPolicy object`
637598
638599 Tool calls require user confirmation before execution.
639600
640601 - `type: optional "web_search"`
641602
642 - `"web_search"`
643
644603 - `user_location: optional BetaManagedAgentsUserLocation or null`
645604
646605 Approximate user location for search result localization.
from line 608
649608
650609 Location precision. Only "approximate" is supported.
651610
652 - `"approximate"`
653
654611 - `city: optional string or null`
655612
656613 City name.
657614
615 minLength: 1, maxLength: 255
616
658617 - `country: optional string or null`
659618
660619 Two-letter ISO 3166-1 country code, uppercase.
from line 622
663622
664623 Region or state name.
665624
625 minLength: 1, maxLength: 255
626
666627 - `timezone: optional string or null`
667628
668629 IANA timezone identifier, e.g. "America/Los_Angeles".
669630
631 minLength: 1, maxLength: 255
632
670633 - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or null`
671634
672635 Default configuration for all tools in a toolset.
from line 642
679642
680643 Permission policy for tool execution.
681644
682 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
645 - `BetaManagedAgentsAlwaysAllowPolicy object`
683646
684647 Tool calls are automatically approved without user confirmation.
685648
686 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
649 - `BetaManagedAgentsAlwaysAskPolicy object`
687650
688651 Tool calls require user confirmation before execution.
689652
690 - `BetaManagedAgentsMCPToolsetParams object { mcp_server_name, type, configs, default_config }`
653 - `BetaManagedAgentsMCPToolsetParams object`
691654
692655 Configuration for tools from an MCP server defined in `mcp_servers`.
693656
from line 658
695658
696659 Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.
697660
661 minLength: 1, maxLength: 255
662
698663 - `type: "mcp_toolset"`
699664
700 - `"mcp_toolset"`
701
702665 - `configs: optional array of BetaManagedAgentsMCPToolConfigParams`
703666
704667 Per-tool configuration overrides.
from line 670
707670
708671 Name of the MCP tool to configure. 1-128 characters.
709672
673 minLength: 1, maxLength: 128
674
710675 - `enabled: optional boolean or null`
711676
712677 Whether this tool is enabled. Overrides the `default_config` setting.
from line 680
715680
716681 Permission policy for tool execution.
717682
718 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
683 - `BetaManagedAgentsAlwaysAllowPolicy object`
719684
720685 Tool calls are automatically approved without user confirmation.
721686
722 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
687 - `BetaManagedAgentsAlwaysAskPolicy object`
723688
724689 Tool calls require user confirmation before execution.
725690
from line 700
735700
736701 Permission policy for tool execution.
737702
738 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
703 - `BetaManagedAgentsAlwaysAllowPolicy object`
739704
740705 Tool calls are automatically approved without user confirmation.
741706
742 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
707 - `BetaManagedAgentsAlwaysAskPolicy object`
743708
744709 Tool calls require user confirmation before execution.
745710
746 - `BetaManagedAgentsCustomToolParams object { description, input_schema, name, type }`
711 - `BetaManagedAgentsCustomToolParams object`
747712
748713 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.
749714
from line 716
751716
752717 Description of what the tool does, shown to the agent to help it decide when to use the tool.
753718
719 minLength: 1
720
754721 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
755722
756723 JSON Schema for custom tool input parameters.
from line 724
757724
758725 - `type: "object"`
759726
760 - `"object"`
761
762727 - `properties: optional map[unknown] or null`
763728
764729 - `required: optional array of string or null`
from line 732
767732
768733 Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.
769734
735 minLength: 1, maxLength: 128
736
770737 - `type: "custom"`
771738
772 - `"custom"`
739## Returns
773740
774### Returns
741- `BetaManagedAgentsAgent object`
775742
776- `BetaManagedAgentsAgent object { id, archived_at, created_at, 12 more }`
777
778743 A Managed Agents `agent`.
779744
780745 - `id: string`
from line 748
783748
784749 A timestamp in RFC 3339 format
785750
751 format: date-time
752
786753 - `created_at: string`
787754
788755 A timestamp in RFC 3339 format
789756
757 format: date-time
758
790759 - `description: string or null`
791760
792761 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
from line 764
795764
796765 - `type: "url"`
797766
798 - `"url"`
799
800767 - `url: string`
801768
802769 - `metadata: map[string]`
from line 842
875842
876843 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
877844
878 - `BetaManagedAgentsEffortLow object { type }`
845 - `BetaManagedAgentsEffortLow object`
879846
880847 Low effort. Favors latency over reasoning depth.
881848
882849 - `type: "low"`
883850
884 - `"low"`
851 - `BetaManagedAgentsEffortMedium object`
885852
886 - `BetaManagedAgentsEffortMedium object { type }`
887
888853 Medium effort. Balances latency and reasoning depth.
889854
890855 - `type: "medium"`
891856
892 - `"medium"`
857 - `BetaManagedAgentsEffortHigh object`
893858
894 - `BetaManagedAgentsEffortHigh object { type }`
895
896859 High effort. Favors reasoning depth.
897860
898861 - `type: "high"`
899862
900 - `"high"`
863 - `BetaManagedAgentsEffortXhigh object`
901864
902 - `BetaManagedAgentsEffortXhigh object { type }`
903
904865 Extra-high effort. Not all models accept this level.
905866
906867 - `type: "xhigh"`
907868
908 - `"xhigh"`
869 - `BetaManagedAgentsEffortMax object`
909870
910 - `BetaManagedAgentsEffortMax object { type }`
911
912871 Maximum effort. Favors reasoning depth over latency.
913872
914873 - `type: "max"`
915874
916 - `"max"`
917
918875 - `inference_geo: optional string`
919876
920877 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 892
935892
936893 Agents the coordinator may spawn as session threads, each resolved to a specific version.
937894
938 - `BetaManagedAgentsAgentReference object { id, type, version }`
895 - `BetaManagedAgentsAgentReference object`
939896
940897 A resolved agent reference with a concrete version.
941898
from line 900
943900
944901 - `type: "agent"`
945902
946 - `"agent"`
947
948903 - `version: number`
949904
950 - `BetaManagedAgentsAdvisor object { model, type }`
905 format: int32
951906
907 - `BetaManagedAgentsAdvisor object`
908
952909 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
953910
954911 - `model: string`
from line 914
957914
958915 - `type: "advisor"`
959916
960 - `"advisor"`
961
962917 - `type: "coordinator"`
963918
964 - `"coordinator"`
965
966919 - `name: string`
967920
968921 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
969922
970 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
923 - `BetaManagedAgentsAnthropicSkill object`
971924
972925 A resolved Anthropic-managed skill.
973926
from line 928
975928
976929 - `type: "anthropic"`
977930
978 - `"anthropic"`
979
980931 - `version: string`
981932
982 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
933 - `BetaManagedAgentsCustomSkill object`
983934
984935 A resolved user-created custom skill.
985936
from line 938
987938
988939 - `type: "custom"`
989940
990 - `"custom"`
991
992941 - `version: string`
993942
994943 - `system: string or null`
from line 944
995944
996945 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
997946
998 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
947 - `BetaManagedAgentsAgentToolset20260401 object`
999948
1000949 - `configs: array of BetaManagedAgentsAgentToolConfig`
1001950
1002 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
951 - `BetaManagedAgentsBashToolConfig object`
1003952
1004953 Configuration for the bash tool.
1005954
from line 956
1007956
1008957 - `name: "bash"`
1009958
1010 - `"bash"`
1011
1012959 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1013960
1014961 Permission policy for tool execution.
1015962
1016 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
963 - `BetaManagedAgentsAlwaysAllowPolicy object`
1017964
1018965 Tool calls are automatically approved without user confirmation.
1019966
1020967 - `type: "always_allow"`
1021968
1022 - `"always_allow"`
969 - `BetaManagedAgentsAlwaysAskPolicy object`
1023970
1024 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1025
1026971 Tool calls require user confirmation before execution.
1027972
1028973 - `type: "always_ask"`
1029974
1030 - `"always_ask"`
1031
1032975 - `type: "bash"`
1033976
1034 - `"bash"`
977 - `BetaManagedAgentsEditToolConfig object`
1035978
1036 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
1037
1038979 Configuration for the edit tool.
1039980
1040981 - `enabled: boolean`
from line 982
1041982
1042983 - `name: "edit"`
1043984
1044 - `"edit"`
1045
1046985 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1047986
1048987 Permission policy for tool execution.
1049988
1050 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
989 - `BetaManagedAgentsAlwaysAllowPolicy object`
1051990
1052991 Tool calls are automatically approved without user confirmation.
1053992
1054 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
993 - `BetaManagedAgentsAlwaysAskPolicy object`
1055994
1056995 Tool calls require user confirmation before execution.
1057996
1058997 - `type: "edit"`
1059998
1060 - `"edit"`
999 - `BetaManagedAgentsReadToolConfig object`
10611000
1062 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
1063
10641001 Configuration for the read tool.
10651002
10661003 - `enabled: boolean`
from line 1004
10671004
10681005 - `name: "read"`
10691006
1070 - `"read"`
1071
10721007 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
10731008
10741009 Permission policy for tool execution.
10751010
1076 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1011 - `BetaManagedAgentsAlwaysAllowPolicy object`
10771012
10781013 Tool calls are automatically approved without user confirmation.
10791014
1080 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1015 - `BetaManagedAgentsAlwaysAskPolicy object`
10811016
10821017 Tool calls require user confirmation before execution.
10831018
10841019 - `type: "read"`
10851020
1086 - `"read"`
1021 - `BetaManagedAgentsWriteToolConfig object`
10871022
1088 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
1089
10901023 Configuration for the write tool.
10911024
10921025 - `enabled: boolean`
from line 1026
10931026
10941027 - `name: "write"`
10951028
1096 - `"write"`
1097
10981029 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
10991030
11001031 Permission policy for tool execution.
11011032
1102 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1033 - `BetaManagedAgentsAlwaysAllowPolicy object`
11031034
11041035 Tool calls are automatically approved without user confirmation.
11051036
1106 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1037 - `BetaManagedAgentsAlwaysAskPolicy object`
11071038
11081039 Tool calls require user confirmation before execution.
11091040
11101041 - `type: "write"`
11111042
1112 - `"write"`
1043 - `BetaManagedAgentsGlobToolConfig object`
11131044
1114 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
1115
11161045 Configuration for the glob tool.
11171046
11181047 - `enabled: boolean`
from line 1048
11191048
11201049 - `name: "glob"`
11211050
1122 - `"glob"`
1123
11241051 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
11251052
11261053 Permission policy for tool execution.
11271054
1128 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1055 - `BetaManagedAgentsAlwaysAllowPolicy object`
11291056
11301057 Tool calls are automatically approved without user confirmation.
11311058
1132 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1059 - `BetaManagedAgentsAlwaysAskPolicy object`
11331060
11341061 Tool calls require user confirmation before execution.
11351062
11361063 - `type: "glob"`
11371064
1138 - `"glob"`
1065 - `BetaManagedAgentsGrepToolConfig object`
11391066
1140 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
1141
11421067 Configuration for the grep tool.
11431068
11441069 - `enabled: boolean`
from line 1070
11451070
11461071 - `name: "grep"`
11471072
1148 - `"grep"`
1149
11501073 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
11511074
11521075 Permission policy for tool execution.
11531076
1154 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1077 - `BetaManagedAgentsAlwaysAllowPolicy object`
11551078
11561079 Tool calls are automatically approved without user confirmation.
11571080
1158 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1081 - `BetaManagedAgentsAlwaysAskPolicy object`
11591082
11601083 Tool calls require user confirmation before execution.
11611084
11621085 - `type: "grep"`
11631086
1164 - `"grep"`
1087 - `BetaManagedAgentsWebFetchToolConfig object`
11651088
1166 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
1167
11681089 Configuration for the web_fetch tool.
11691090
11701091 - `enabled: boolean`
from line 1092
11711092
11721093 - `name: "web_fetch"`
11731094
1174 - `"web_fetch"`
1175
11761095 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
11771096
11781097 Permission policy for tool execution.
11791098
1180 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1099 - `BetaManagedAgentsAlwaysAllowPolicy object`
11811100
11821101 Tool calls are automatically approved without user confirmation.
11831102
1184 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1103 - `BetaManagedAgentsAlwaysAskPolicy object`
11851104
11861105 Tool calls require user confirmation before execution.
11871106
11881107 - `type: "web_fetch"`
11891108
1190 - `"web_fetch"`
1191
11921109 - `allowed_domains: optional array of string`
11931110
11941111 - `blocked_domains: optional array of string`
from line 1112
11951112
11961113 - `max_content_tokens: optional number or null`
11971114
1198 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
1115 format: int32
11991116
1117 - `BetaManagedAgentsWebSearchToolConfig object`
1118
12001119 Configuration for the web_search tool.
12011120
12021121 - `enabled: boolean`
from line 1122
12031122
12041123 - `name: "web_search"`
12051124
1206 - `"web_search"`
1207
12081125 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
12091126
12101127 Permission policy for tool execution.
12111128
1212 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1129 - `BetaManagedAgentsAlwaysAllowPolicy object`
12131130
12141131 Tool calls are automatically approved without user confirmation.
12151132
1216 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1133 - `BetaManagedAgentsAlwaysAskPolicy object`
12171134
12181135 Tool calls require user confirmation before execution.
12191136
12201137 - `type: "web_search"`
12211138
1222 - `"web_search"`
1223
12241139 - `allowed_domains: optional array of string`
12251140
12261141 - `blocked_domains: optional array of string`
from line 1148
12331148
12341149 Location precision. Only "approximate" is supported.
12351150
1236 - `"approximate"`
1237
12381151 - `city: optional string or null`
12391152
12401153 City name.
12411154
1155 minLength: 1, maxLength: 255
1156
12421157 - `country: optional string or null`
12431158
12441159 Two-letter ISO 3166-1 country code, uppercase.
from line 1162
12471162
12481163 Region or state name.
12491164
1165 minLength: 1, maxLength: 255
1166
12501167 - `timezone: optional string or null`
12511168
12521169 IANA timezone identifier, e.g. "America/Los_Angeles".
12531170
1171 minLength: 1, maxLength: 255
1172
12541173 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
12551174
12561175 Resolved default configuration for agent tools.
from line 1180
12611180
12621181 Permission policy for tool execution.
12631182
1264 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1183 - `BetaManagedAgentsAlwaysAllowPolicy object`
12651184
12661185 Tool calls are automatically approved without user confirmation.
12671186
1268 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1187 - `BetaManagedAgentsAlwaysAskPolicy object`
12691188
12701189 Tool calls require user confirmation before execution.
12711190
12721191 - `type: "agent_toolset_20260401"`
12731192
1274 - `"agent_toolset_20260401"`
1193 - `BetaManagedAgentsMCPToolset object`
12751194
1276 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
1277
12781195 - `configs: array of BetaManagedAgentsMCPToolConfig`
12791196
12801197 - `enabled: boolean`
from line 1202
12851202
12861203 Permission policy for tool execution.
12871204
1288 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1205 - `BetaManagedAgentsAlwaysAllowPolicy object`
12891206
12901207 Tool calls are automatically approved without user confirmation.
12911208
1292 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1209 - `BetaManagedAgentsAlwaysAskPolicy object`
12931210
12941211 Tool calls require user confirmation before execution.
12951212
from line 1220
13031220
13041221 Permission policy for tool execution.
13051222
1306 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1223 - `BetaManagedAgentsAlwaysAllowPolicy object`
13071224
13081225 Tool calls are automatically approved without user confirmation.
13091226
1310 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1227 - `BetaManagedAgentsAlwaysAskPolicy object`
13111228
13121229 Tool calls require user confirmation before execution.
13131230
from line 1232
13151232
13161233 - `type: "mcp_toolset"`
13171234
1318 - `"mcp_toolset"`
1235 - `BetaManagedAgentsCustomTool object`
13191236
1320 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
1321
13221237 A custom tool as returned in API responses.
13231238
13241239 - `description: string`
from line 1244
13291244
13301245 - `type: "object"`
13311246
1332 - `"object"`
1333
13341247 - `properties: optional map[unknown] or null`
13351248
13361249 - `required: optional array of string or null`
from line 1252
13391252
13401253 - `type: "custom"`
13411254
1342 - `"custom"`
1343
13441255 - `type: "agent"`
13451256
1346 - `"agent"`
1347
13481257 - `updated_at: string`
13491258
13501259 A timestamp in RFC 3339 format
13511260
1261 format: date-time
1262
13521263 - `version: number`
13531264
13541265 The agent's current version. Starts at 1 and increments when the agent is modified.
13551266
1356### Example
1267 format: int32
13571268
1358```http
1269## Example
1270
1271```bash
13591272curl https://api.anthropic.com/v1/agents \
13601273 -H 'Content-Type: application/json' \
13611274 -H 'anthropic-version: 2023-06-01' \
from line 1290
13771290 }'
13781291```
13791292
1380#### Response
1293### Response (200)
13811294
13821295```json
13831296{
api/beta/agents/list Changed · +76 / -127 lines
# List Agents ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List Agents ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: List Agents
3url: https://platform.claude.com/docs/en/api/beta/agents/list
4---
1# List Agents
52
6## List Agents
3**GET** `/v1/agents`
74
8**get** `/v1/agents`
9
105List Agents
116
12### Query Parameters
7## Query parameters
138
149- `"created_at[gte]": optional string`
1510
1611 Return agents created at or after this time (inclusive).
1712
13 format: date-time
14
1815- `"created_at[lte]": optional string`
1916
2017 Return agents created at or before this time (inclusive).
2118
19 format: date-time
20
2221- `include_archived: optional boolean`
2322
2423 Include archived agents in results. Defaults to false.
from line 26
2726
2827 Maximum results per page. Default 20, maximum 100.
2928
29 format: int32
30
3031- `page: optional string`
3132
3233 Opaque pagination cursor from a previous response.
3334
34### Header Parameters
35## Headers
3536
3637- `"anthropic-beta": optional array of AnthropicBeta`
3738
from line 110
109110
110111 - `"mid-conversation-tool-changes-2026-07-01"`
111112
112### Returns
113## Returns
113114
114115- `data: array of BetaManagedAgentsAgent`
115116
from line 122
121122
122123 A timestamp in RFC 3339 format
123124
125 format: date-time
126
124127 - `created_at: string`
125128
126129 A timestamp in RFC 3339 format
127130
131 format: date-time
132
128133 - `description: string or null`
129134
130135 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
from line 138
133138
134139 - `type: "url"`
135140
136 - `"url"`
137
138141 - `url: string`
139142
140143 - `metadata: map[string]`
from line 216
213216
214217 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
215218
216 - `BetaManagedAgentsEffortLow object { type }`
219 - `BetaManagedAgentsEffortLow object`
217220
218221 Low effort. Favors latency over reasoning depth.
219222
220223 - `type: "low"`
221224
222 - `"low"`
225 - `BetaManagedAgentsEffortMedium object`
223226
224 - `BetaManagedAgentsEffortMedium object { type }`
225
226227 Medium effort. Balances latency and reasoning depth.
227228
228229 - `type: "medium"`
229230
230 - `"medium"`
231 - `BetaManagedAgentsEffortHigh object`
231232
232 - `BetaManagedAgentsEffortHigh object { type }`
233
234233 High effort. Favors reasoning depth.
235234
236235 - `type: "high"`
237236
238 - `"high"`
237 - `BetaManagedAgentsEffortXhigh object`
239238
240 - `BetaManagedAgentsEffortXhigh object { type }`
241
242239 Extra-high effort. Not all models accept this level.
243240
244241 - `type: "xhigh"`
245242
246 - `"xhigh"`
243 - `BetaManagedAgentsEffortMax object`
247244
248 - `BetaManagedAgentsEffortMax object { type }`
249
250245 Maximum effort. Favors reasoning depth over latency.
251246
252247 - `type: "max"`
253248
254 - `"max"`
255
256249 - `inference_geo: optional string`
257250
258251 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 266
273266
274267 Agents the coordinator may spawn as session threads, each resolved to a specific version.
275268
276 - `BetaManagedAgentsAgentReference object { id, type, version }`
269 - `BetaManagedAgentsAgentReference object`
277270
278271 A resolved agent reference with a concrete version.
279272
from line 274
281274
282275 - `type: "agent"`
283276
284 - `"agent"`
285
286277 - `version: number`
287278
288 - `BetaManagedAgentsAdvisor object { model, type }`
279 format: int32
289280
281 - `BetaManagedAgentsAdvisor object`
282
290283 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
291284
292285 - `model: string`
from line 288
295288
296289 - `type: "advisor"`
297290
298 - `"advisor"`
299
300291 - `type: "coordinator"`
301292
302 - `"coordinator"`
303
304293 - `name: string`
305294
306295 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
307296
308 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
297 - `BetaManagedAgentsAnthropicSkill object`
309298
310299 A resolved Anthropic-managed skill.
311300
from line 302
313302
314303 - `type: "anthropic"`
315304
316 - `"anthropic"`
317
318305 - `version: string`
319306
320 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
307 - `BetaManagedAgentsCustomSkill object`
321308
322309 A resolved user-created custom skill.
323310
from line 312
325312
326313 - `type: "custom"`
327314
328 - `"custom"`
329
330315 - `version: string`
331316
332317 - `system: string or null`
from line 318
333318
334319 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
335320
336 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
321 - `BetaManagedAgentsAgentToolset20260401 object`
337322
338323 - `configs: array of BetaManagedAgentsAgentToolConfig`
339324
340 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
325 - `BetaManagedAgentsBashToolConfig object`
341326
342327 Configuration for the bash tool.
343328
from line 330
345330
346331 - `name: "bash"`
347332
348 - `"bash"`
349
350333 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
351334
352335 Permission policy for tool execution.
353336
354 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
337 - `BetaManagedAgentsAlwaysAllowPolicy object`
355338
356339 Tool calls are automatically approved without user confirmation.
357340
358341 - `type: "always_allow"`
359342
360 - `"always_allow"`
343 - `BetaManagedAgentsAlwaysAskPolicy object`
361344
362 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
363
364345 Tool calls require user confirmation before execution.
365346
366347 - `type: "always_ask"`
367348
368 - `"always_ask"`
369
370349 - `type: "bash"`
371350
372 - `"bash"`
351 - `BetaManagedAgentsEditToolConfig object`
373352
374 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
375
376353 Configuration for the edit tool.
377354
378355 - `enabled: boolean`
from line 356
379356
380357 - `name: "edit"`
381358
382 - `"edit"`
383
384359 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
385360
386361 Permission policy for tool execution.
387362
388 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
363 - `BetaManagedAgentsAlwaysAllowPolicy object`
389364
390365 Tool calls are automatically approved without user confirmation.
391366
392 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
367 - `BetaManagedAgentsAlwaysAskPolicy object`
393368
394369 Tool calls require user confirmation before execution.
395370
396371 - `type: "edit"`
397372
398 - `"edit"`
373 - `BetaManagedAgentsReadToolConfig object`
399374
400 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
401
402375 Configuration for the read tool.
403376
404377 - `enabled: boolean`
from line 378
405378
406379 - `name: "read"`
407380
408 - `"read"`
409
410381 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
411382
412383 Permission policy for tool execution.
413384
414 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
385 - `BetaManagedAgentsAlwaysAllowPolicy object`
415386
416387 Tool calls are automatically approved without user confirmation.
417388
418 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
389 - `BetaManagedAgentsAlwaysAskPolicy object`
419390
420391 Tool calls require user confirmation before execution.
421392
422393 - `type: "read"`
423394
424 - `"read"`
395 - `BetaManagedAgentsWriteToolConfig object`
425396
426 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
427
428397 Configuration for the write tool.
429398
430399 - `enabled: boolean`
from line 400
431400
432401 - `name: "write"`
433402
434 - `"write"`
435
436403 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
437404
438405 Permission policy for tool execution.
439406
440 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
407 - `BetaManagedAgentsAlwaysAllowPolicy object`
441408
442409 Tool calls are automatically approved without user confirmation.
443410
444 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
411 - `BetaManagedAgentsAlwaysAskPolicy object`
445412
446413 Tool calls require user confirmation before execution.
447414
448415 - `type: "write"`
449416
450 - `"write"`
417 - `BetaManagedAgentsGlobToolConfig object`
451418
452 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
453
454419 Configuration for the glob tool.
455420
456421 - `enabled: boolean`
from line 422
457422
458423 - `name: "glob"`
459424
460 - `"glob"`
461
462425 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
463426
464427 Permission policy for tool execution.
465428
466 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
429 - `BetaManagedAgentsAlwaysAllowPolicy object`
467430
468431 Tool calls are automatically approved without user confirmation.
469432
470 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
433 - `BetaManagedAgentsAlwaysAskPolicy object`
471434
472435 Tool calls require user confirmation before execution.
473436
474437 - `type: "glob"`
475438
476 - `"glob"`
439 - `BetaManagedAgentsGrepToolConfig object`
477440
478 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
479
480441 Configuration for the grep tool.
481442
482443 - `enabled: boolean`
from line 444
483444
484445 - `name: "grep"`
485446
486 - `"grep"`
487
488447 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
489448
490449 Permission policy for tool execution.
491450
492 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
451 - `BetaManagedAgentsAlwaysAllowPolicy object`
493452
494453 Tool calls are automatically approved without user confirmation.
495454
496 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
455 - `BetaManagedAgentsAlwaysAskPolicy object`
497456
498457 Tool calls require user confirmation before execution.
499458
500459 - `type: "grep"`
501460
502 - `"grep"`
461 - `BetaManagedAgentsWebFetchToolConfig object`
503462
504 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
505
506463 Configuration for the web_fetch tool.
507464
508465 - `enabled: boolean`
from line 466
509466
510467 - `name: "web_fetch"`
511468
512 - `"web_fetch"`
513
514469 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
515470
516471 Permission policy for tool execution.
517472
518 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
473 - `BetaManagedAgentsAlwaysAllowPolicy object`
519474
520475 Tool calls are automatically approved without user confirmation.
521476
522 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
477 - `BetaManagedAgentsAlwaysAskPolicy object`
523478
524479 Tool calls require user confirmation before execution.
525480
526481 - `type: "web_fetch"`
527482
528 - `"web_fetch"`
529
530483 - `allowed_domains: optional array of string`
531484
532485 - `blocked_domains: optional array of string`
from line 486
533486
534487 - `max_content_tokens: optional number or null`
535488
536 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
489 format: int32
537490
491 - `BetaManagedAgentsWebSearchToolConfig object`
492
538493 Configuration for the web_search tool.
539494
540495 - `enabled: boolean`
from line 496
541496
542497 - `name: "web_search"`
543498
544 - `"web_search"`
545
546499 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
547500
548501 Permission policy for tool execution.
549502
550 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
503 - `BetaManagedAgentsAlwaysAllowPolicy object`
551504
552505 Tool calls are automatically approved without user confirmation.
553506
554 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
507 - `BetaManagedAgentsAlwaysAskPolicy object`
555508
556509 Tool calls require user confirmation before execution.
557510
558511 - `type: "web_search"`
559512
560 - `"web_search"`
561
562513 - `allowed_domains: optional array of string`
563514
564515 - `blocked_domains: optional array of string`
from line 522
571522
572523 Location precision. Only "approximate" is supported.
573524
574 - `"approximate"`
575
576525 - `city: optional string or null`
577526
578527 City name.
579528
529 minLength: 1, maxLength: 255
530
580531 - `country: optional string or null`
581532
582533 Two-letter ISO 3166-1 country code, uppercase.
from line 536
585536
586537 Region or state name.
587538
539 minLength: 1, maxLength: 255
540
588541 - `timezone: optional string or null`
589542
590543 IANA timezone identifier, e.g. "America/Los_Angeles".
591544
545 minLength: 1, maxLength: 255
546
592547 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
593548
594549 Resolved default configuration for agent tools.
from line 554
599554
600555 Permission policy for tool execution.
601556
602 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
557 - `BetaManagedAgentsAlwaysAllowPolicy object`
603558
604559 Tool calls are automatically approved without user confirmation.
605560
606 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
561 - `BetaManagedAgentsAlwaysAskPolicy object`
607562
608563 Tool calls require user confirmation before execution.
609564
610565 - `type: "agent_toolset_20260401"`
611566
612 - `"agent_toolset_20260401"`
567 - `BetaManagedAgentsMCPToolset object`
613568
614 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
615
616569 - `configs: array of BetaManagedAgentsMCPToolConfig`
617570
618571 - `enabled: boolean`
from line 576
623576
624577 Permission policy for tool execution.
625578
626 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
579 - `BetaManagedAgentsAlwaysAllowPolicy object`
627580
628581 Tool calls are automatically approved without user confirmation.
629582
630 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
583 - `BetaManagedAgentsAlwaysAskPolicy object`
631584
632585 Tool calls require user confirmation before execution.
633586
from line 594
641594
642595 Permission policy for tool execution.
643596
644 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
597 - `BetaManagedAgentsAlwaysAllowPolicy object`
645598
646599 Tool calls are automatically approved without user confirmation.
647600
648 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
601 - `BetaManagedAgentsAlwaysAskPolicy object`
649602
650603 Tool calls require user confirmation before execution.
651604
from line 606
653606
654607 - `type: "mcp_toolset"`
655608
656 - `"mcp_toolset"`
609 - `BetaManagedAgentsCustomTool object`
657610
658 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
659
660611 A custom tool as returned in API responses.
661612
662613 - `description: string`
from line 618
667618
668619 - `type: "object"`
669620
670 - `"object"`
671
672621 - `properties: optional map[unknown] or null`
673622
674623 - `required: optional array of string or null`
from line 626
677626
678627 - `type: "custom"`
679628
680 - `"custom"`
681
682629 - `type: "agent"`
683630
684 - `"agent"`
685
686631 - `updated_at: string`
687632
688633 A timestamp in RFC 3339 format
689634
635 format: date-time
636
690637 - `version: number`
691638
692639 The agent's current version. Starts at 1 and increments when the agent is modified.
693640
641 format: int32
642
694643- `next_page: optional string or null`
695644
696645 Opaque cursor for the next page. Null when no more results.
697646
698### Example
647## Example
699648
700```http
649```bash
701650curl https://api.anthropic.com/v1/agents \
702651 -H 'anthropic-version: 2023-06-01' \
703652 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 653
704653 -H "X-Api-Key: $ANTHROPIC_API_KEY"
705654```
706655
707#### Response
656### Response (200)
708657
709658```json
710659{
api/beta/agents/retrieve Changed · +75 / -130 lines
# Get Agent ## Path parameters ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## Get Agent ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Get Agent
3url: https://platform.claude.com/docs/en/api/beta/agents/retrieve
4---
1# Get Agent
52
6## Get Agent
3**GET** `/v1/agents/{agent_id}`
74
8**get** `/v1/agents/{agent_id}`
9
105Get Agent
116
12### Path Parameters
7## Path parameters
138
149- `agent_id: string`
1510
16### Query Parameters
11## Query parameters
1712
1813- `version: optional number`
1914
2015 Agent version. Omit for the most recent version. Must be at least 1 if specified.
2116
22### Header Parameters
17 format: int32
2318
19## Headers
20
2421- `"anthropic-beta": optional array of AnthropicBeta`
2522
2623 Optional header to specify the beta version(s) you want to use.
from line 94
9794
9895 - `"mid-conversation-tool-changes-2026-07-01"`
9996
100### Returns
97## Returns
10198
102- `BetaManagedAgentsAgent object { id, archived_at, created_at, 12 more }`
99- `BetaManagedAgentsAgent object`
103100
104101 A Managed Agents `agent`.
105102
from line 106
109106
110107 A timestamp in RFC 3339 format
111108
109 format: date-time
110
112111 - `created_at: string`
113112
114113 A timestamp in RFC 3339 format
115114
115 format: date-time
116
116117 - `description: string or null`
117118
118119 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
from line 122
121122
122123 - `type: "url"`
123124
124 - `"url"`
125
126125 - `url: string`
127126
128127 - `metadata: map[string]`
from line 200
201200
202201 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
203202
204 - `BetaManagedAgentsEffortLow object { type }`
203 - `BetaManagedAgentsEffortLow object`
205204
206205 Low effort. Favors latency over reasoning depth.
207206
208207 - `type: "low"`
209208
210 - `"low"`
209 - `BetaManagedAgentsEffortMedium object`
211210
212 - `BetaManagedAgentsEffortMedium object { type }`
213
214211 Medium effort. Balances latency and reasoning depth.
215212
216213 - `type: "medium"`
217214
218 - `"medium"`
215 - `BetaManagedAgentsEffortHigh object`
219216
220 - `BetaManagedAgentsEffortHigh object { type }`
221
222217 High effort. Favors reasoning depth.
223218
224219 - `type: "high"`
225220
226 - `"high"`
221 - `BetaManagedAgentsEffortXhigh object`
227222
228 - `BetaManagedAgentsEffortXhigh object { type }`
229
230223 Extra-high effort. Not all models accept this level.
231224
232225 - `type: "xhigh"`
233226
234 - `"xhigh"`
227 - `BetaManagedAgentsEffortMax object`
235228
236 - `BetaManagedAgentsEffortMax object { type }`
237
238229 Maximum effort. Favors reasoning depth over latency.
239230
240231 - `type: "max"`
241232
242 - `"max"`
243
244233 - `inference_geo: optional string`
245234
246235 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 250
261250
262251 Agents the coordinator may spawn as session threads, each resolved to a specific version.
263252
264 - `BetaManagedAgentsAgentReference object { id, type, version }`
253 - `BetaManagedAgentsAgentReference object`
265254
266255 A resolved agent reference with a concrete version.
267256
from line 258
269258
270259 - `type: "agent"`
271260
272 - `"agent"`
273
274261 - `version: number`
275262
276 - `BetaManagedAgentsAdvisor object { model, type }`
263 format: int32
277264
265 - `BetaManagedAgentsAdvisor object`
266
278267 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
279268
280269 - `model: string`
from line 272
283272
284273 - `type: "advisor"`
285274
286 - `"advisor"`
287
288275 - `type: "coordinator"`
289276
290 - `"coordinator"`
291
292277 - `name: string`
293278
294279 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
295280
296 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
281 - `BetaManagedAgentsAnthropicSkill object`
297282
298283 A resolved Anthropic-managed skill.
299284
from line 286
301286
302287 - `type: "anthropic"`
303288
304 - `"anthropic"`
305
306289 - `version: string`
307290
308 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
291 - `BetaManagedAgentsCustomSkill object`
309292
310293 A resolved user-created custom skill.
311294
from line 296
313296
314297 - `type: "custom"`
315298
316 - `"custom"`
317
318299 - `version: string`
319300
320301 - `system: string or null`
from line 302
321302
322303 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
323304
324 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
305 - `BetaManagedAgentsAgentToolset20260401 object`
325306
326307 - `configs: array of BetaManagedAgentsAgentToolConfig`
327308
328 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
309 - `BetaManagedAgentsBashToolConfig object`
329310
330311 Configuration for the bash tool.
331312
from line 314
333314
334315 - `name: "bash"`
335316
336 - `"bash"`
337
338317 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
339318
340319 Permission policy for tool execution.
341320
342 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
321 - `BetaManagedAgentsAlwaysAllowPolicy object`
343322
344323 Tool calls are automatically approved without user confirmation.
345324
346325 - `type: "always_allow"`
347326
348 - `"always_allow"`
327 - `BetaManagedAgentsAlwaysAskPolicy object`
349328
350 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
351
352329 Tool calls require user confirmation before execution.
353330
354331 - `type: "always_ask"`
355332
356 - `"always_ask"`
357
358333 - `type: "bash"`
359334
360 - `"bash"`
335 - `BetaManagedAgentsEditToolConfig object`
361336
362 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
363
364337 Configuration for the edit tool.
365338
366339 - `enabled: boolean`
from line 340
367340
368341 - `name: "edit"`
369342
370 - `"edit"`
371
372343 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
373344
374345 Permission policy for tool execution.
375346
376 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
347 - `BetaManagedAgentsAlwaysAllowPolicy object`
377348
378349 Tool calls are automatically approved without user confirmation.
379350
380 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
351 - `BetaManagedAgentsAlwaysAskPolicy object`
381352
382353 Tool calls require user confirmation before execution.
383354
384355 - `type: "edit"`
385356
386 - `"edit"`
357 - `BetaManagedAgentsReadToolConfig object`
387358
388 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
389
390359 Configuration for the read tool.
391360
392361 - `enabled: boolean`
from line 362
393362
394363 - `name: "read"`
395364
396 - `"read"`
397
398365 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
399366
400367 Permission policy for tool execution.
401368
402 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
369 - `BetaManagedAgentsAlwaysAllowPolicy object`
403370
404371 Tool calls are automatically approved without user confirmation.
405372
406 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
373 - `BetaManagedAgentsAlwaysAskPolicy object`
407374
408375 Tool calls require user confirmation before execution.
409376
410377 - `type: "read"`
411378
412 - `"read"`
379 - `BetaManagedAgentsWriteToolConfig object`
413380
414 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
415
416381 Configuration for the write tool.
417382
418383 - `enabled: boolean`
from line 384
419384
420385 - `name: "write"`
421386
422 - `"write"`
423
424387 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
425388
426389 Permission policy for tool execution.
427390
428 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
391 - `BetaManagedAgentsAlwaysAllowPolicy object`
429392
430393 Tool calls are automatically approved without user confirmation.
431394
432 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
395 - `BetaManagedAgentsAlwaysAskPolicy object`
433396
434397 Tool calls require user confirmation before execution.
435398
436399 - `type: "write"`
437400
438 - `"write"`
401 - `BetaManagedAgentsGlobToolConfig object`
439402
440 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
441
442403 Configuration for the glob tool.
443404
444405 - `enabled: boolean`
from line 406
445406
446407 - `name: "glob"`
447408
448 - `"glob"`
449
450409 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
451410
452411 Permission policy for tool execution.
453412
454 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
413 - `BetaManagedAgentsAlwaysAllowPolicy object`
455414
456415 Tool calls are automatically approved without user confirmation.
457416
458 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
417 - `BetaManagedAgentsAlwaysAskPolicy object`
459418
460419 Tool calls require user confirmation before execution.
461420
462421 - `type: "glob"`
463422
464 - `"glob"`
423 - `BetaManagedAgentsGrepToolConfig object`
465424
466 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
467
468425 Configuration for the grep tool.
469426
470427 - `enabled: boolean`
from line 428
471428
472429 - `name: "grep"`
473430
474 - `"grep"`
475
476431 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
477432
478433 Permission policy for tool execution.
479434
480 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
435 - `BetaManagedAgentsAlwaysAllowPolicy object`
481436
482437 Tool calls are automatically approved without user confirmation.
483438
484 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
439 - `BetaManagedAgentsAlwaysAskPolicy object`
485440
486441 Tool calls require user confirmation before execution.
487442
488443 - `type: "grep"`
489444
490 - `"grep"`
445 - `BetaManagedAgentsWebFetchToolConfig object`
491446
492 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
493
494447 Configuration for the web_fetch tool.
495448
496449 - `enabled: boolean`
from line 450
497450
498451 - `name: "web_fetch"`
499452
500 - `"web_fetch"`
501
502453 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
503454
504455 Permission policy for tool execution.
505456
506 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
457 - `BetaManagedAgentsAlwaysAllowPolicy object`
507458
508459 Tool calls are automatically approved without user confirmation.
509460
510 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
461 - `BetaManagedAgentsAlwaysAskPolicy object`
511462
512463 Tool calls require user confirmation before execution.
513464
514465 - `type: "web_fetch"`
515466
516 - `"web_fetch"`
517
518467 - `allowed_domains: optional array of string`
519468
520469 - `blocked_domains: optional array of string`
from line 470
521470
522471 - `max_content_tokens: optional number or null`
523472
524 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
473 format: int32
525474
475 - `BetaManagedAgentsWebSearchToolConfig object`
476
526477 Configuration for the web_search tool.
527478
528479 - `enabled: boolean`
from line 480
529480
530481 - `name: "web_search"`
531482
532 - `"web_search"`
533
534483 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
535484
536485 Permission policy for tool execution.
537486
538 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
487 - `BetaManagedAgentsAlwaysAllowPolicy object`
539488
540489 Tool calls are automatically approved without user confirmation.
541490
542 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
491 - `BetaManagedAgentsAlwaysAskPolicy object`
543492
544493 Tool calls require user confirmation before execution.
545494
546495 - `type: "web_search"`
547496
548 - `"web_search"`
549
550497 - `allowed_domains: optional array of string`
551498
552499 - `blocked_domains: optional array of string`
from line 506
559506
560507 Location precision. Only "approximate" is supported.
561508
562 - `"approximate"`
563
564509 - `city: optional string or null`
565510
566511 City name.
567512
513 minLength: 1, maxLength: 255
514
568515 - `country: optional string or null`
569516
570517 Two-letter ISO 3166-1 country code, uppercase.
from line 520
573520
574521 Region or state name.
575522
523 minLength: 1, maxLength: 255
524
576525 - `timezone: optional string or null`
577526
578527 IANA timezone identifier, e.g. "America/Los_Angeles".
579528
529 minLength: 1, maxLength: 255
530
580531 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
581532
582533 Resolved default configuration for agent tools.
from line 538
587538
588539 Permission policy for tool execution.
589540
590 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
541 - `BetaManagedAgentsAlwaysAllowPolicy object`
591542
592543 Tool calls are automatically approved without user confirmation.
593544
594 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
545 - `BetaManagedAgentsAlwaysAskPolicy object`
595546
596547 Tool calls require user confirmation before execution.
597548
598549 - `type: "agent_toolset_20260401"`
599550
600 - `"agent_toolset_20260401"`
551 - `BetaManagedAgentsMCPToolset object`
601552
602 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
603
604553 - `configs: array of BetaManagedAgentsMCPToolConfig`
605554
606555 - `enabled: boolean`
from line 560
611560
612561 Permission policy for tool execution.
613562
614 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
563 - `BetaManagedAgentsAlwaysAllowPolicy object`
615564
616565 Tool calls are automatically approved without user confirmation.
617566
618 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
567 - `BetaManagedAgentsAlwaysAskPolicy object`
619568
620569 Tool calls require user confirmation before execution.
621570
from line 578
629578
630579 Permission policy for tool execution.
631580
632 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
581 - `BetaManagedAgentsAlwaysAllowPolicy object`
633582
634583 Tool calls are automatically approved without user confirmation.
635584
636 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
585 - `BetaManagedAgentsAlwaysAskPolicy object`
637586
638587 Tool calls require user confirmation before execution.
639588
from line 590
641590
642591 - `type: "mcp_toolset"`
643592
644 - `"mcp_toolset"`
593 - `BetaManagedAgentsCustomTool object`
645594
646 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
647
648595 A custom tool as returned in API responses.
649596
650597 - `description: string`
from line 602
655602
656603 - `type: "object"`
657604
658 - `"object"`
659
660605 - `properties: optional map[unknown] or null`
661606
662607 - `required: optional array of string or null`
from line 610
665610
666611 - `type: "custom"`
667612
668 - `"custom"`
669
670613 - `type: "agent"`
671614
672 - `"agent"`
673
674615 - `updated_at: string`
675616
676617 A timestamp in RFC 3339 format
677618
619 format: date-time
620
678621 - `version: number`
679622
680623 The agent's current version. Starts at 1 and increments when the agent is modified.
681624
682### Example
625 format: int32
683626
684```http
627## Example
628
629```bash
685630curl https://api.anthropic.com/v1/agents/$AGENT_ID \
686631 -H 'anthropic-version: 2023-06-01' \
687632 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 633
688633 -H "X-Api-Key: $ANTHROPIC_API_KEY"
689634```
690635
691#### Response
636### Response (200)
692637
693638```json
694639{
api/beta/agents/update Changed · +159 / -244 lines
# Update Agent ## Path parameters ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Update Agent ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Update Agent
3url: https://platform.claude.com/docs/en/api/beta/agents/update
4---
1# Update Agent
52
6## Update Agent
3**POST** `/v1/agents/{agent_id}`
74
8**post** `/v1/agents/{agent_id}`
9
105Update Agent
116
12### Path Parameters
7## Path parameters
138
149- `agent_id: string`
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Body Parameters
89## Body parameters
9590
9691- `description: optional string or null`
9792
9893 Description. Omit to preserve; send empty string or null to clear.
9994
95 maxLength: 2048
96
10097- `mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams or null`
10198
10299 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).
from line 102
105102
106103 Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.
107104
105 minLength: 1, maxLength: 255
106
108107 - `type: "url"`
109108
110 - `"url"`
111
112109 - `url: string`
113110
114111 Endpoint URL for the MCP server.
115112
113 maxLength: 2048
114
116115- `metadata: optional map[string] or null`
117116
118117 Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars.
from line 186
187186
188187 - `string`
189188
190 - `BetaManagedAgentsModelConfigParams object { id, effort, inference_geo, speed }`
189 - `BetaManagedAgentsModelConfigParams object`
191190
192191 An object that defines additional configuration control over model use
193192
from line 214
215214
216215 - `"max"`
217216
218 - `BetaManagedAgentsEffortLow object { type }`
217 - `BetaManagedAgentsEffortLow object`
219218
220219 Low effort. Favors latency over reasoning depth.
221220
222221 - `type: "low"`
223222
224 - `"low"`
223 - `BetaManagedAgentsEffortMedium object`
225224
226 - `BetaManagedAgentsEffortMedium object { type }`
227
228225 Medium effort. Balances latency and reasoning depth.
229226
230227 - `type: "medium"`
231228
232 - `"medium"`
229 - `BetaManagedAgentsEffortHigh object`
233230
234 - `BetaManagedAgentsEffortHigh object { type }`
235
236231 High effort. Favors reasoning depth.
237232
238233 - `type: "high"`
239234
240 - `"high"`
235 - `BetaManagedAgentsEffortXhigh object`
241236
242 - `BetaManagedAgentsEffortXhigh object { type }`
243
244237 Extra-high effort. Not all models accept this level.
245238
246239 - `type: "xhigh"`
247240
248 - `"xhigh"`
241 - `BetaManagedAgentsEffortMax object`
249242
250 - `BetaManagedAgentsEffortMax object { type }`
251
252243 Maximum effort. Favors reasoning depth over latency.
253244
254245 - `type: "max"`
255246
256 - `"max"`
257
258247 - `inference_geo: optional string or null`
259248
260249 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. On update, `model` is whole-object replacement — omitting inference_geo clears it.
from line 266
277266
278267 - `string`
279268
280 - `BetaManagedAgentsAgentParams object { id, type, version }`
269 - `BetaManagedAgentsAgentParams object`
281270
282271 Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version
283272
from line 274
285274
286275 The `agent` ID.
287276
277 minLength: 1, maxLength: 128
278
288279 - `type: "agent"`
289280
290 - `"agent"`
291
292281 - `version: optional number`
293282
294283 The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.
295284
296 - `BetaManagedAgentsMultiagentSelfParams object { type }`
285 format: int32
297286
287 - `BetaManagedAgentsMultiagentSelfParams object`
288
298289 Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference.
299290
300291 - `type: "self"`
301292
302 - `"self"`
293 - `BetaManagedAgentsAdvisorParams object`
303294
304 - `BetaManagedAgentsAdvisorParams object { model, type }`
305
306295 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`.
307296
308297 - `model: string`
from line 298
309298
310299 A Claude model id. The model must be permitted as an advisor for this agent's model — see the sessions/threads/advisor spec.
311300
301 minLength: 1, maxLength: 256
302
312303 - `type: "advisor"`
313304
314 - `"advisor"`
315
316305 - `type: "coordinator"`
317306
318 - `"coordinator"`
319
320307- `name: optional string`
321308
322309 Human-readable name. Must be non-empty. Omit to preserve. Cannot be cleared.
323310
311 maxLength: 256
312
324313- `skills: optional array of BetaManagedAgentsSkillParams or null`
325314
326315 Skills. Full replacement. Omit to preserve; send empty array or null to clear.
327316
328 - `BetaManagedAgentsAnthropicSkillParams object { skill_id, type, version }`
317 - `BetaManagedAgentsAnthropicSkillParams object`
329318
330319 An Anthropic-managed skill.
331320
from line 322
333322
334323 Identifier of the Anthropic skill (e.g., "xlsx").
335324
325 minLength: 1, maxLength: 64
326
336327 - `type: "anthropic"`
337328
338 - `"anthropic"`
339
340329 - `version: optional string or null`
341330
342331 Version to pin. Defaults to latest if omitted.
343332
344 - `BetaManagedAgentsCustomSkillParams object { skill_id, type, version }`
333 minLength: 1, maxLength: 64
345334
335 - `BetaManagedAgentsCustomSkillParams object`
336
346337 A user-created custom skill.
347338
348339 - `skill_id: string`
from line 340
349340
350341 Tagged ID of the custom skill (e.g., "skill_01XJ5...").
351342
343 minLength: 1, maxLength: 64
344
352345 - `type: "custom"`
353346
354 - `"custom"`
355
356347 - `version: optional string or null`
357348
358349 Version to pin. Defaults to latest if omitted.
359350
351 minLength: 1, maxLength: 64
352
360353- `system: optional string or null`
361354
362355 System prompt. Omit to preserve; send empty string or null to clear.
363356
357 maxLength: 100000
358
364359- `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams or null`
365360
366361 Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed.
367362
368 - `BetaManagedAgentsAgentToolset20260401Params object { type, configs, default_config }`
363 - `BetaManagedAgentsAgentToolset20260401Params object`
369364
370365 Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.
371366
372367 - `type: "agent_toolset_20260401"`
373368
374 - `"agent_toolset_20260401"`
375
376369 - `configs: optional array of BetaManagedAgentsAgentToolConfigParams`
377370
378371 Per-tool configuration overrides.
379372
380 - `BetaManagedAgentsBashToolConfigParams object { name, enabled, permission_policy, type }`
373 - `BetaManagedAgentsBashToolConfigParams object`
381374
382375 Configuration override for the bash tool.
383376
from line 378
385378
386379 Must be "bash".
387380
388 - `"bash"`
389
390381 - `enabled: optional boolean or null`
391382
392383 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 386
395386
396387 Permission policy for tool execution.
397388
398 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
389 - `BetaManagedAgentsAlwaysAllowPolicy object`
399390
400391 Tool calls are automatically approved without user confirmation.
401392
402393 - `type: "always_allow"`
403394
404 - `"always_allow"`
395 - `BetaManagedAgentsAlwaysAskPolicy object`
405396
406 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
407
408397 Tool calls require user confirmation before execution.
409398
410399 - `type: "always_ask"`
411400
412 - `"always_ask"`
413
414401 - `type: optional "bash"`
415402
416 - `"bash"`
403 - `BetaManagedAgentsEditToolConfigParams object`
417404
418 - `BetaManagedAgentsEditToolConfigParams object { name, enabled, permission_policy, type }`
419
420405 Configuration override for the edit tool.
421406
422407 - `name: "edit"`
from line 408
423408
424409 Must be "edit".
425410
426 - `"edit"`
427
428411 - `enabled: optional boolean or null`
429412
430413 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 416
433416
434417 Permission policy for tool execution.
435418
436 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
419 - `BetaManagedAgentsAlwaysAllowPolicy object`
437420
438421 Tool calls are automatically approved without user confirmation.
439422
440 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
423 - `BetaManagedAgentsAlwaysAskPolicy object`
441424
442425 Tool calls require user confirmation before execution.
443426
444427 - `type: optional "edit"`
445428
446 - `"edit"`
429 - `BetaManagedAgentsReadToolConfigParams object`
447430
448 - `BetaManagedAgentsReadToolConfigParams object { name, enabled, permission_policy, type }`
449
450431 Configuration override for the read tool.
451432
452433 - `name: "read"`
from line 434
453434
454435 Must be "read".
455436
456 - `"read"`
457
458437 - `enabled: optional boolean or null`
459438
460439 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 442
463442
464443 Permission policy for tool execution.
465444
466 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
445 - `BetaManagedAgentsAlwaysAllowPolicy object`
467446
468447 Tool calls are automatically approved without user confirmation.
469448
470 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
449 - `BetaManagedAgentsAlwaysAskPolicy object`
471450
472451 Tool calls require user confirmation before execution.
473452
474453 - `type: optional "read"`
475454
476 - `"read"`
455 - `BetaManagedAgentsWriteToolConfigParams object`
477456
478 - `BetaManagedAgentsWriteToolConfigParams object { name, enabled, permission_policy, type }`
479
480457 Configuration override for the write tool.
481458
482459 - `name: "write"`
from line 460
483460
484461 Must be "write".
485462
486 - `"write"`
487
488463 - `enabled: optional boolean or null`
489464
490465 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 468
493468
494469 Permission policy for tool execution.
495470
496 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
471 - `BetaManagedAgentsAlwaysAllowPolicy object`
497472
498473 Tool calls are automatically approved without user confirmation.
499474
500 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
475 - `BetaManagedAgentsAlwaysAskPolicy object`
501476
502477 Tool calls require user confirmation before execution.
503478
504479 - `type: optional "write"`
505480
506 - `"write"`
481 - `BetaManagedAgentsGlobToolConfigParams object`
507482
508 - `BetaManagedAgentsGlobToolConfigParams object { name, enabled, permission_policy, type }`
509
510483 Configuration override for the glob tool.
511484
512485 - `name: "glob"`
from line 486
513486
514487 Must be "glob".
515488
516 - `"glob"`
517
518489 - `enabled: optional boolean or null`
519490
520491 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 494
523494
524495 Permission policy for tool execution.
525496
526 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
497 - `BetaManagedAgentsAlwaysAllowPolicy object`
527498
528499 Tool calls are automatically approved without user confirmation.
529500
530 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
501 - `BetaManagedAgentsAlwaysAskPolicy object`
531502
532503 Tool calls require user confirmation before execution.
533504
534505 - `type: optional "glob"`
535506
536 - `"glob"`
507 - `BetaManagedAgentsGrepToolConfigParams object`
537508
538 - `BetaManagedAgentsGrepToolConfigParams object { name, enabled, permission_policy, type }`
539
540509 Configuration override for the grep tool.
541510
542511 - `name: "grep"`
from line 512
543512
544513 Must be "grep".
545514
546 - `"grep"`
547
548515 - `enabled: optional boolean or null`
549516
550517 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 520
553520
554521 Permission policy for tool execution.
555522
556 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
523 - `BetaManagedAgentsAlwaysAllowPolicy object`
557524
558525 Tool calls are automatically approved without user confirmation.
559526
560 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
527 - `BetaManagedAgentsAlwaysAskPolicy object`
561528
562529 Tool calls require user confirmation before execution.
563530
564531 - `type: optional "grep"`
565532
566 - `"grep"`
533 - `BetaManagedAgentsWebFetchToolConfigParams object`
567534
568 - `BetaManagedAgentsWebFetchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }`
569
570535 Configuration override for the web_fetch tool.
571536
572537 - `name: "web_fetch"`
from line 538
573538
574539 Must be "web_fetch".
575540
576 - `"web_fetch"`
577
578541 - `allowed_domains: optional array of string`
579542
580543 Only fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
from line 554
591554
592555 Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs.
593556
557 format: int32
558
594559 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
595560
596561 Permission policy for tool execution.
597562
598 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
563 - `BetaManagedAgentsAlwaysAllowPolicy object`
599564
600565 Tool calls are automatically approved without user confirmation.
601566
602 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
567 - `BetaManagedAgentsAlwaysAskPolicy object`
603568
604569 Tool calls require user confirmation before execution.
605570
606571 - `type: optional "web_fetch"`
607572
608 - `"web_fetch"`
573 - `BetaManagedAgentsWebSearchToolConfigParams object`
609574
610 - `BetaManagedAgentsWebSearchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }`
611
612575 Configuration override for the web_search tool.
613576
614577 - `name: "web_search"`
from line 578
615578
616579 Must be "web_search".
617580
618 - `"web_search"`
619
620581 - `allowed_domains: optional array of string`
621582
622583 Only return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
from line 594
633594
634595 Permission policy for tool execution.
635596
636 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
597 - `BetaManagedAgentsAlwaysAllowPolicy object`
637598
638599 Tool calls are automatically approved without user confirmation.
639600
640 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
601 - `BetaManagedAgentsAlwaysAskPolicy object`
641602
642603 Tool calls require user confirmation before execution.
643604
644605 - `type: optional "web_search"`
645606
646 - `"web_search"`
647
648607 - `user_location: optional BetaManagedAgentsUserLocation or null`
649608
650609 Approximate user location for search result localization.
from line 612
653612
654613 Location precision. Only "approximate" is supported.
655614
656 - `"approximate"`
657
658615 - `city: optional string or null`
659616
660617 City name.
661618
619 minLength: 1, maxLength: 255
620
662621 - `country: optional string or null`
663622
664623 Two-letter ISO 3166-1 country code, uppercase.
from line 626
667626
668627 Region or state name.
669628
629 minLength: 1, maxLength: 255
630
670631 - `timezone: optional string or null`
671632
672633 IANA timezone identifier, e.g. "America/Los_Angeles".
673634
635 minLength: 1, maxLength: 255
636
674637 - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or null`
675638
676639 Default configuration for all tools in a toolset.
from line 646
683646
684647 Permission policy for tool execution.
685648
686 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
649 - `BetaManagedAgentsAlwaysAllowPolicy object`
687650
688651 Tool calls are automatically approved without user confirmation.
689652
690 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
653 - `BetaManagedAgentsAlwaysAskPolicy object`
691654
692655 Tool calls require user confirmation before execution.
693656
694 - `BetaManagedAgentsMCPToolsetParams object { mcp_server_name, type, configs, default_config }`
657 - `BetaManagedAgentsMCPToolsetParams object`
695658
696659 Configuration for tools from an MCP server defined in `mcp_servers`.
697660
from line 662
699662
700663 Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.
701664
665 minLength: 1, maxLength: 255
666
702667 - `type: "mcp_toolset"`
703668
704 - `"mcp_toolset"`
705
706669 - `configs: optional array of BetaManagedAgentsMCPToolConfigParams`
707670
708671 Per-tool configuration overrides.
from line 674
711674
712675 Name of the MCP tool to configure. 1-128 characters.
713676
677 minLength: 1, maxLength: 128
678
714679 - `enabled: optional boolean or null`
715680
716681 Whether this tool is enabled. Overrides the `default_config` setting.
from line 684
719684
720685 Permission policy for tool execution.
721686
722 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
687 - `BetaManagedAgentsAlwaysAllowPolicy object`
723688
724689 Tool calls are automatically approved without user confirmation.
725690
726 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
691 - `BetaManagedAgentsAlwaysAskPolicy object`
727692
728693 Tool calls require user confirmation before execution.
729694
from line 704
739704
740705 Permission policy for tool execution.
741706
742 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
707 - `BetaManagedAgentsAlwaysAllowPolicy object`
743708
744709 Tool calls are automatically approved without user confirmation.
745710
746 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
711 - `BetaManagedAgentsAlwaysAskPolicy object`
747712
748713 Tool calls require user confirmation before execution.
749714
750 - `BetaManagedAgentsCustomToolParams object { description, input_schema, name, type }`
715 - `BetaManagedAgentsCustomToolParams object`
751716
752717 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.
753718
from line 720
755720
756721 Description of what the tool does, shown to the agent to help it decide when to use the tool.
757722
723 minLength: 1
724
758725 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
759726
760727 JSON Schema for custom tool input parameters.
from line 728
761728
762729 - `type: "object"`
763730
764 - `"object"`
765
766731 - `properties: optional map[unknown] or null`
767732
768733 - `required: optional array of string or null`
from line 736
771736
772737 Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.
773738
739 minLength: 1, maxLength: 128
740
774741 - `type: "custom"`
775742
776 - `"custom"`
777
778743- `version: optional number`
779744
780745 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.
781746
782### Returns
747 format: int32
783748
784- `BetaManagedAgentsAgent object { id, archived_at, created_at, 12 more }`
749## Returns
785750
751- `BetaManagedAgentsAgent object`
752
786753 A Managed Agents `agent`.
787754
788755 - `id: string`
from line 758
791758
792759 A timestamp in RFC 3339 format
793760
761 format: date-time
762
794763 - `created_at: string`
795764
796765 A timestamp in RFC 3339 format
797766
767 format: date-time
768
798769 - `description: string or null`
799770
800771 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
from line 774
803774
804775 - `type: "url"`
805776
806 - `"url"`
807
808777 - `url: string`
809778
810779 - `metadata: map[string]`
from line 852
883852
884853 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
885854
886 - `BetaManagedAgentsEffortLow object { type }`
855 - `BetaManagedAgentsEffortLow object`
887856
888857 Low effort. Favors latency over reasoning depth.
889858
890859 - `type: "low"`
891860
892 - `"low"`
861 - `BetaManagedAgentsEffortMedium object`
893862
894 - `BetaManagedAgentsEffortMedium object { type }`
895
896863 Medium effort. Balances latency and reasoning depth.
897864
898865 - `type: "medium"`
899866
900 - `"medium"`
867 - `BetaManagedAgentsEffortHigh object`
901868
902 - `BetaManagedAgentsEffortHigh object { type }`
903
904869 High effort. Favors reasoning depth.
905870
906871 - `type: "high"`
907872
908 - `"high"`
873 - `BetaManagedAgentsEffortXhigh object`
909874
910 - `BetaManagedAgentsEffortXhigh object { type }`
911
912875 Extra-high effort. Not all models accept this level.
913876
914877 - `type: "xhigh"`
915878
916 - `"xhigh"`
879 - `BetaManagedAgentsEffortMax object`
917880
918 - `BetaManagedAgentsEffortMax object { type }`
919
920881 Maximum effort. Favors reasoning depth over latency.
921882
922883 - `type: "max"`
923884
924 - `"max"`
925
926885 - `inference_geo: optional string`
927886
928887 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 902
943902
944903 Agents the coordinator may spawn as session threads, each resolved to a specific version.
945904
946 - `BetaManagedAgentsAgentReference object { id, type, version }`
905 - `BetaManagedAgentsAgentReference object`
947906
948907 A resolved agent reference with a concrete version.
949908
from line 910
951910
952911 - `type: "agent"`
953912
954 - `"agent"`
955
956913 - `version: number`
957914
958 - `BetaManagedAgentsAdvisor object { model, type }`
915 format: int32
959916
917 - `BetaManagedAgentsAdvisor object`
918
960919 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
961920
962921 - `model: string`
from line 924
965924
966925 - `type: "advisor"`
967926
968 - `"advisor"`
969
970927 - `type: "coordinator"`
971928
972 - `"coordinator"`
973
974929 - `name: string`
975930
976931 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
977932
978 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
933 - `BetaManagedAgentsAnthropicSkill object`
979934
980935 A resolved Anthropic-managed skill.
981936
from line 938
983938
984939 - `type: "anthropic"`
985940
986 - `"anthropic"`
987
988941 - `version: string`
989942
990 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
943 - `BetaManagedAgentsCustomSkill object`
991944
992945 A resolved user-created custom skill.
993946
from line 948
995948
996949 - `type: "custom"`
997950
998 - `"custom"`
999
1000951 - `version: string`
1001952
1002953 - `system: string or null`
from line 954
1003954
1004955 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
1005956
1006 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
957 - `BetaManagedAgentsAgentToolset20260401 object`
1007958
1008959 - `configs: array of BetaManagedAgentsAgentToolConfig`
1009960
1010 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
961 - `BetaManagedAgentsBashToolConfig object`
1011962
1012963 Configuration for the bash tool.
1013964
from line 966
1015966
1016967 - `name: "bash"`
1017968
1018 - `"bash"`
1019
1020969 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1021970
1022971 Permission policy for tool execution.
1023972
1024 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
973 - `BetaManagedAgentsAlwaysAllowPolicy object`
1025974
1026975 Tool calls are automatically approved without user confirmation.
1027976
1028977 - `type: "always_allow"`
1029978
1030 - `"always_allow"`
979 - `BetaManagedAgentsAlwaysAskPolicy object`
1031980
1032 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1033
1034981 Tool calls require user confirmation before execution.
1035982
1036983 - `type: "always_ask"`
1037984
1038 - `"always_ask"`
1039
1040985 - `type: "bash"`
1041986
1042 - `"bash"`
987 - `BetaManagedAgentsEditToolConfig object`
1043988
1044 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
1045
1046989 Configuration for the edit tool.
1047990
1048991 - `enabled: boolean`
from line 992
1049992
1050993 - `name: "edit"`
1051994
1052 - `"edit"`
1053
1054995 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1055996
1056997 Permission policy for tool execution.
1057998
1058 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
999 - `BetaManagedAgentsAlwaysAllowPolicy object`
10591000
10601001 Tool calls are automatically approved without user confirmation.
10611002
1062 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1003 - `BetaManagedAgentsAlwaysAskPolicy object`
10631004
10641005 Tool calls require user confirmation before execution.
10651006
10661007 - `type: "edit"`
10671008
1068 - `"edit"`
1009 - `BetaManagedAgentsReadToolConfig object`
10691010
1070 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
1071
10721011 Configuration for the read tool.
10731012
10741013 - `enabled: boolean`
from line 1014
10751014
10761015 - `name: "read"`
10771016
1078 - `"read"`
1079
10801017 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
10811018
10821019 Permission policy for tool execution.
10831020
1084 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1021 - `BetaManagedAgentsAlwaysAllowPolicy object`
10851022
10861023 Tool calls are automatically approved without user confirmation.
10871024
1088 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1025 - `BetaManagedAgentsAlwaysAskPolicy object`
10891026
10901027 Tool calls require user confirmation before execution.
10911028
10921029 - `type: "read"`
10931030
1094 - `"read"`
1031 - `BetaManagedAgentsWriteToolConfig object`
10951032
1096 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
1097
10981033 Configuration for the write tool.
10991034
11001035 - `enabled: boolean`
from line 1036
11011036
11021037 - `name: "write"`
11031038
1104 - `"write"`
1105
11061039 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
11071040
11081041 Permission policy for tool execution.
11091042
1110 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1043 - `BetaManagedAgentsAlwaysAllowPolicy object`
11111044
11121045 Tool calls are automatically approved without user confirmation.
11131046
1114 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1047 - `BetaManagedAgentsAlwaysAskPolicy object`
11151048
11161049 Tool calls require user confirmation before execution.
11171050
11181051 - `type: "write"`
11191052
1120 - `"write"`
1053 - `BetaManagedAgentsGlobToolConfig object`
11211054
1122 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
1123
11241055 Configuration for the glob tool.
11251056
11261057 - `enabled: boolean`
from line 1058
11271058
11281059 - `name: "glob"`
11291060
1130 - `"glob"`
1131
11321061 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
11331062
11341063 Permission policy for tool execution.
11351064
1136 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1065 - `BetaManagedAgentsAlwaysAllowPolicy object`
11371066
11381067 Tool calls are automatically approved without user confirmation.
11391068
1140 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1069 - `BetaManagedAgentsAlwaysAskPolicy object`
11411070
11421071 Tool calls require user confirmation before execution.
11431072
11441073 - `type: "glob"`
11451074
1146 - `"glob"`
1075 - `BetaManagedAgentsGrepToolConfig object`
11471076
1148 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
1149
11501077 Configuration for the grep tool.
11511078
11521079 - `enabled: boolean`
from line 1080
11531080
11541081 - `name: "grep"`
11551082
1156 - `"grep"`
1157
11581083 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
11591084
11601085 Permission policy for tool execution.
11611086
1162 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1087 - `BetaManagedAgentsAlwaysAllowPolicy object`
11631088
11641089 Tool calls are automatically approved without user confirmation.
11651090
1166 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1091 - `BetaManagedAgentsAlwaysAskPolicy object`
11671092
11681093 Tool calls require user confirmation before execution.
11691094
11701095 - `type: "grep"`
11711096
1172 - `"grep"`
1097 - `BetaManagedAgentsWebFetchToolConfig object`
11731098
1174 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
1175
11761099 Configuration for the web_fetch tool.
11771100
11781101 - `enabled: boolean`
from line 1102
11791102
11801103 - `name: "web_fetch"`
11811104
1182 - `"web_fetch"`
1183
11841105 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
11851106
11861107 Permission policy for tool execution.
11871108
1188 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1109 - `BetaManagedAgentsAlwaysAllowPolicy object`
11891110
11901111 Tool calls are automatically approved without user confirmation.
11911112
1192 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1113 - `BetaManagedAgentsAlwaysAskPolicy object`
11931114
11941115 Tool calls require user confirmation before execution.
11951116
11961117 - `type: "web_fetch"`
11971118
1198 - `"web_fetch"`
1199
12001119 - `allowed_domains: optional array of string`
12011120
12021121 - `blocked_domains: optional array of string`
from line 1122
12031122
12041123 - `max_content_tokens: optional number or null`
12051124
1206 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
1125 format: int32
12071126
1127 - `BetaManagedAgentsWebSearchToolConfig object`
1128
12081129 Configuration for the web_search tool.
12091130
12101131 - `enabled: boolean`
from line 1132
12111132
12121133 - `name: "web_search"`
12131134
1214 - `"web_search"`
1215
12161135 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
12171136
12181137 Permission policy for tool execution.
12191138
1220 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1139 - `BetaManagedAgentsAlwaysAllowPolicy object`
12211140
12221141 Tool calls are automatically approved without user confirmation.
12231142
1224 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1143 - `BetaManagedAgentsAlwaysAskPolicy object`
12251144
12261145 Tool calls require user confirmation before execution.
12271146
12281147 - `type: "web_search"`
12291148
1230 - `"web_search"`
1231
12321149 - `allowed_domains: optional array of string`
12331150
12341151 - `blocked_domains: optional array of string`
from line 1158
12411158
12421159 Location precision. Only "approximate" is supported.
12431160
1244 - `"approximate"`
1245
12461161 - `city: optional string or null`
12471162
12481163 City name.
12491164
1165 minLength: 1, maxLength: 255
1166
12501167 - `country: optional string or null`
12511168
12521169 Two-letter ISO 3166-1 country code, uppercase.
from line 1172
12551172
12561173 Region or state name.
12571174
1175 minLength: 1, maxLength: 255
1176
12581177 - `timezone: optional string or null`
12591178
12601179 IANA timezone identifier, e.g. "America/Los_Angeles".
12611180
1181 minLength: 1, maxLength: 255
1182
12621183 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
12631184
12641185 Resolved default configuration for agent tools.
from line 1190
12691190
12701191 Permission policy for tool execution.
12711192
1272 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1193 - `BetaManagedAgentsAlwaysAllowPolicy object`
12731194
12741195 Tool calls are automatically approved without user confirmation.
12751196
1276 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1197 - `BetaManagedAgentsAlwaysAskPolicy object`
12771198
12781199 Tool calls require user confirmation before execution.
12791200
12801201 - `type: "agent_toolset_20260401"`
12811202
1282 - `"agent_toolset_20260401"`
1203 - `BetaManagedAgentsMCPToolset object`
12831204
1284 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
1285
12861205 - `configs: array of BetaManagedAgentsMCPToolConfig`
12871206
12881207 - `enabled: boolean`
from line 1212
12931212
12941213 Permission policy for tool execution.
12951214
1296 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1215 - `BetaManagedAgentsAlwaysAllowPolicy object`
12971216
12981217 Tool calls are automatically approved without user confirmation.
12991218
1300 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1219 - `BetaManagedAgentsAlwaysAskPolicy object`
13011220
13021221 Tool calls require user confirmation before execution.
13031222
from line 1230
13111230
13121231 Permission policy for tool execution.
13131232
1314 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1233 - `BetaManagedAgentsAlwaysAllowPolicy object`
13151234
13161235 Tool calls are automatically approved without user confirmation.
13171236
1318 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1237 - `BetaManagedAgentsAlwaysAskPolicy object`
13191238
13201239 Tool calls require user confirmation before execution.
13211240
from line 1242
13231242
13241243 - `type: "mcp_toolset"`
13251244
1326 - `"mcp_toolset"`
1245 - `BetaManagedAgentsCustomTool object`
13271246
1328 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
1329
13301247 A custom tool as returned in API responses.
13311248
13321249 - `description: string`
from line 1254
13371254
13381255 - `type: "object"`
13391256
1340 - `"object"`
1341
13421257 - `properties: optional map[unknown] or null`
13431258
13441259 - `required: optional array of string or null`
from line 1262
13471262
13481263 - `type: "custom"`
13491264
1350 - `"custom"`
1351
13521265 - `type: "agent"`
13531266
1354 - `"agent"`
1355
13561267 - `updated_at: string`
13571268
13581269 A timestamp in RFC 3339 format
13591270
1271 format: date-time
1272
13601273 - `version: number`
13611274
13621275 The agent's current version. Starts at 1 and increments when the agent is modified.
13631276
1364### Example
1277 format: int32
13651278
1366```http
1279## Example
1280
1281```bash
13671282curl https://api.anthropic.com/v1/agents/$AGENT_ID \
13681283 -H 'Content-Type: application/json' \
13691284 -H 'anthropic-version: 2023-06-01' \
from line 1291
13761291 }'
13771292```
13781293
1379#### Response
1294### Response (200)
13801295
13811296```json
13821297{
api/beta/agents/versions Changed · +68 / -123 lines
### Path parameters ### Query parameters ### Headers #### Response (200) ### Path Parameters ### Query Parameters ### Header Parameters #### Response
from line 1
1---
2title: Versions
3url: https://platform.claude.com/docs/en/api/beta/agents/versions
4---
5
61# Versions
72
83## List Agent Versions
94
10**get** `/v1/agents/{agent_id}/versions`
5**GET** `/v1/agents/{agent_id}/versions`
116
127List Agent Versions
138
14### Path Parameters
9### Path parameters
1510
1611- `agent_id: string`
1712
18### Query Parameters
13### Query parameters
1914
2015- `limit: optional number`
2116
2217 Maximum results per page. Default 20, maximum 100.
2318
19 format: int32
20
2421- `page: optional string`
2522
2623 Opaque pagination cursor.
2724
28### Header Parameters
25### Headers
2926
3027- `"anthropic-beta": optional array of AnthropicBeta`
3128
from line 112
115112
116113 A timestamp in RFC 3339 format
117114
115 format: date-time
116
118117 - `created_at: string`
119118
120119 A timestamp in RFC 3339 format
121120
121 format: date-time
122
122123 - `description: string or null`
123124
124125 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
from line 128
127128
128129 - `type: "url"`
129130
130 - `"url"`
131
132131 - `url: string`
133132
134133 - `metadata: map[string]`
from line 206
207206
208207 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
209208
210 - `BetaManagedAgentsEffortLow object { type }`
209 - `BetaManagedAgentsEffortLow object`
211210
212211 Low effort. Favors latency over reasoning depth.
213212
214213 - `type: "low"`
215214
216 - `"low"`
215 - `BetaManagedAgentsEffortMedium object`
217216
218 - `BetaManagedAgentsEffortMedium object { type }`
219
220217 Medium effort. Balances latency and reasoning depth.
221218
222219 - `type: "medium"`
223220
224 - `"medium"`
221 - `BetaManagedAgentsEffortHigh object`
225222
226 - `BetaManagedAgentsEffortHigh object { type }`
227
228223 High effort. Favors reasoning depth.
229224
230225 - `type: "high"`
231226
232 - `"high"`
227 - `BetaManagedAgentsEffortXhigh object`
233228
234 - `BetaManagedAgentsEffortXhigh object { type }`
235
236229 Extra-high effort. Not all models accept this level.
237230
238231 - `type: "xhigh"`
239232
240 - `"xhigh"`
233 - `BetaManagedAgentsEffortMax object`
241234
242 - `BetaManagedAgentsEffortMax object { type }`
243
244235 Maximum effort. Favors reasoning depth over latency.
245236
246237 - `type: "max"`
247238
248 - `"max"`
249
250239 - `inference_geo: optional string`
251240
252241 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 256
267256
268257 Agents the coordinator may spawn as session threads, each resolved to a specific version.
269258
270 - `BetaManagedAgentsAgentReference object { id, type, version }`
259 - `BetaManagedAgentsAgentReference object`
271260
272261 A resolved agent reference with a concrete version.
273262
from line 264
275264
276265 - `type: "agent"`
277266
278 - `"agent"`
279
280267 - `version: number`
281268
282 - `BetaManagedAgentsAdvisor object { model, type }`
269 format: int32
283270
271 - `BetaManagedAgentsAdvisor object`
272
284273 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
285274
286275 - `model: string`
from line 278
289278
290279 - `type: "advisor"`
291280
292 - `"advisor"`
293
294281 - `type: "coordinator"`
295282
296 - `"coordinator"`
297
298283 - `name: string`
299284
300285 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
301286
302 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
287 - `BetaManagedAgentsAnthropicSkill object`
303288
304289 A resolved Anthropic-managed skill.
305290
from line 292
307292
308293 - `type: "anthropic"`
309294
310 - `"anthropic"`
311
312295 - `version: string`
313296
314 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
297 - `BetaManagedAgentsCustomSkill object`
315298
316299 A resolved user-created custom skill.
317300
from line 302
319302
320303 - `type: "custom"`
321304
322 - `"custom"`
323
324305 - `version: string`
325306
326307 - `system: string or null`
from line 308
327308
328309 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
329310
330 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
311 - `BetaManagedAgentsAgentToolset20260401 object`
331312
332313 - `configs: array of BetaManagedAgentsAgentToolConfig`
333314
334 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
315 - `BetaManagedAgentsBashToolConfig object`
335316
336317 Configuration for the bash tool.
337318
from line 320
339320
340321 - `name: "bash"`
341322
342 - `"bash"`
343
344323 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
345324
346325 Permission policy for tool execution.
347326
348 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
327 - `BetaManagedAgentsAlwaysAllowPolicy object`
349328
350329 Tool calls are automatically approved without user confirmation.
351330
352331 - `type: "always_allow"`
353332
354 - `"always_allow"`
333 - `BetaManagedAgentsAlwaysAskPolicy object`
355334
356 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
357
358335 Tool calls require user confirmation before execution.
359336
360337 - `type: "always_ask"`
361338
362 - `"always_ask"`
363
364339 - `type: "bash"`
365340
366 - `"bash"`
341 - `BetaManagedAgentsEditToolConfig object`
367342
368 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
369
370343 Configuration for the edit tool.
371344
372345 - `enabled: boolean`
from line 346
373346
374347 - `name: "edit"`
375348
376 - `"edit"`
377
378349 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
379350
380351 Permission policy for tool execution.
381352
382 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
353 - `BetaManagedAgentsAlwaysAllowPolicy object`
383354
384355 Tool calls are automatically approved without user confirmation.
385356
386 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
357 - `BetaManagedAgentsAlwaysAskPolicy object`
387358
388359 Tool calls require user confirmation before execution.
389360
390361 - `type: "edit"`
391362
392 - `"edit"`
363 - `BetaManagedAgentsReadToolConfig object`
393364
394 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
395
396365 Configuration for the read tool.
397366
398367 - `enabled: boolean`
from line 368
399368
400369 - `name: "read"`
401370
402 - `"read"`
403
404371 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
405372
406373 Permission policy for tool execution.
407374
408 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
375 - `BetaManagedAgentsAlwaysAllowPolicy object`
409376
410377 Tool calls are automatically approved without user confirmation.
411378
412 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
379 - `BetaManagedAgentsAlwaysAskPolicy object`
413380
414381 Tool calls require user confirmation before execution.
415382
416383 - `type: "read"`
417384
418 - `"read"`
385 - `BetaManagedAgentsWriteToolConfig object`
419386
420 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
421
422387 Configuration for the write tool.
423388
424389 - `enabled: boolean`
from line 390
425390
426391 - `name: "write"`
427392
428 - `"write"`
429
430393 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
431394
432395 Permission policy for tool execution.
433396
434 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
397 - `BetaManagedAgentsAlwaysAllowPolicy object`
435398
436399 Tool calls are automatically approved without user confirmation.
437400
438 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
401 - `BetaManagedAgentsAlwaysAskPolicy object`
439402
440403 Tool calls require user confirmation before execution.
441404
442405 - `type: "write"`
443406
444 - `"write"`
407 - `BetaManagedAgentsGlobToolConfig object`
445408
446 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
447
448409 Configuration for the glob tool.
449410
450411 - `enabled: boolean`
from line 412
451412
452413 - `name: "glob"`
453414
454 - `"glob"`
455
456415 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
457416
458417 Permission policy for tool execution.
459418
460 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
419 - `BetaManagedAgentsAlwaysAllowPolicy object`
461420
462421 Tool calls are automatically approved without user confirmation.
463422
464 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
423 - `BetaManagedAgentsAlwaysAskPolicy object`
465424
466425 Tool calls require user confirmation before execution.
467426
468427 - `type: "glob"`
469428
470 - `"glob"`
429 - `BetaManagedAgentsGrepToolConfig object`
471430
472 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
473
474431 Configuration for the grep tool.
475432
476433 - `enabled: boolean`
from line 434
477434
478435 - `name: "grep"`
479436
480 - `"grep"`
481
482437 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
483438
484439 Permission policy for tool execution.
485440
486 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
441 - `BetaManagedAgentsAlwaysAllowPolicy object`
487442
488443 Tool calls are automatically approved without user confirmation.
489444
490 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
445 - `BetaManagedAgentsAlwaysAskPolicy object`
491446
492447 Tool calls require user confirmation before execution.
493448
494449 - `type: "grep"`
495450
496 - `"grep"`
451 - `BetaManagedAgentsWebFetchToolConfig object`
497452
498 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
499
500453 Configuration for the web_fetch tool.
501454
502455 - `enabled: boolean`
from line 456
503456
504457 - `name: "web_fetch"`
505458
506 - `"web_fetch"`
507
508459 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
509460
510461 Permission policy for tool execution.
511462
512 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
463 - `BetaManagedAgentsAlwaysAllowPolicy object`
513464
514465 Tool calls are automatically approved without user confirmation.
515466
516 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
467 - `BetaManagedAgentsAlwaysAskPolicy object`
517468
518469 Tool calls require user confirmation before execution.
519470
520471 - `type: "web_fetch"`
521472
522 - `"web_fetch"`
523
524473 - `allowed_domains: optional array of string`
525474
526475 - `blocked_domains: optional array of string`
from line 476
527476
528477 - `max_content_tokens: optional number or null`
529478
530 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
479 format: int32
531480
481 - `BetaManagedAgentsWebSearchToolConfig object`
482
532483 Configuration for the web_search tool.
533484
534485 - `enabled: boolean`
from line 486
535486
536487 - `name: "web_search"`
537488
538 - `"web_search"`
539
540489 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
541490
542491 Permission policy for tool execution.
543492
544 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
493 - `BetaManagedAgentsAlwaysAllowPolicy object`
545494
546495 Tool calls are automatically approved without user confirmation.
547496
548 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
497 - `BetaManagedAgentsAlwaysAskPolicy object`
549498
550499 Tool calls require user confirmation before execution.
551500
552501 - `type: "web_search"`
553502
554 - `"web_search"`
555
556503 - `allowed_domains: optional array of string`
557504
558505 - `blocked_domains: optional array of string`
from line 512
565512
566513 Location precision. Only "approximate" is supported.
567514
568 - `"approximate"`
569
570515 - `city: optional string or null`
571516
572517 City name.
573518
519 minLength: 1, maxLength: 255
520
574521 - `country: optional string or null`
575522
576523 Two-letter ISO 3166-1 country code, uppercase.
from line 526
579526
580527 Region or state name.
581528
529 minLength: 1, maxLength: 255
530
582531 - `timezone: optional string or null`
583532
584533 IANA timezone identifier, e.g. "America/Los_Angeles".
585534
535 minLength: 1, maxLength: 255
536
586537 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
587538
588539 Resolved default configuration for agent tools.
from line 544
593544
594545 Permission policy for tool execution.
595546
596 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
547 - `BetaManagedAgentsAlwaysAllowPolicy object`
597548
598549 Tool calls are automatically approved without user confirmation.
599550
600 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
551 - `BetaManagedAgentsAlwaysAskPolicy object`
601552
602553 Tool calls require user confirmation before execution.
603554
604555 - `type: "agent_toolset_20260401"`
605556
606 - `"agent_toolset_20260401"`
557 - `BetaManagedAgentsMCPToolset object`
607558
608 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
609
610559 - `configs: array of BetaManagedAgentsMCPToolConfig`
611560
612561 - `enabled: boolean`
from line 566
617566
618567 Permission policy for tool execution.
619568
620 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
569 - `BetaManagedAgentsAlwaysAllowPolicy object`
621570
622571 Tool calls are automatically approved without user confirmation.
623572
624 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
573 - `BetaManagedAgentsAlwaysAskPolicy object`
625574
626575 Tool calls require user confirmation before execution.
627576
from line 584
635584
636585 Permission policy for tool execution.
637586
638 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
587 - `BetaManagedAgentsAlwaysAllowPolicy object`
639588
640589 Tool calls are automatically approved without user confirmation.
641590
642 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
591 - `BetaManagedAgentsAlwaysAskPolicy object`
643592
644593 Tool calls require user confirmation before execution.
645594
from line 596
647596
648597 - `type: "mcp_toolset"`
649598
650 - `"mcp_toolset"`
599 - `BetaManagedAgentsCustomTool object`
651600
652 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
653
654601 A custom tool as returned in API responses.
655602
656603 - `description: string`
from line 608
661608
662609 - `type: "object"`
663610
664 - `"object"`
665
666611 - `properties: optional map[unknown] or null`
667612
668613 - `required: optional array of string or null`
from line 616
671616
672617 - `type: "custom"`
673618
674 - `"custom"`
675
676619 - `type: "agent"`
677620
678 - `"agent"`
679
680621 - `updated_at: string`
681622
682623 A timestamp in RFC 3339 format
683624
625 format: date-time
626
684627 - `version: number`
685628
686629 The agent's current version. Starts at 1 and increments when the agent is modified.
687630
631 format: int32
632
688633- `next_page: optional string or null`
689634
690635 Opaque cursor for the next page. Null when no more results.
from line 636
691636
692637### Example
693638
694```http
639```bash
695640curl https://api.anthropic.com/v1/agents/$AGENT_ID/versions \
696641 -H 'anthropic-version: 2023-06-01' \
697642 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 643
698643 -H "X-Api-Key: $ANTHROPIC_API_KEY"
699644```
700645
701#### Response
646#### Response (200)
702647
703648```json
704649{
api/beta/agents/versions/list Changed · +73 / -128 lines
# List Agent Versions ## Path parameters ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List Agent Versions ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
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{
api/beta/deployment_runs Changed · +119 / -252 lines
### Query parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ## Domain types ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ## Domain Types
from line 1
1---
2title: Deployment Runs
3url: https://platform.claude.com/docs/en/api/beta/deployment_runs
4---
5
61# Deployment Runs
72
83## List Deployment Runs
94
10**get** `/v1/deployment_runs`
5**GET** `/v1/deployment_runs`
116
127List Deployment Runs
138
14### Query Parameters
9### Query parameters
1510
1611- `"created_at[gt]": optional string`
1712
1813 Return runs created strictly after this time (exclusive).
1914
15 format: date-time
16
2017- `"created_at[gte]": optional string`
2118
2219 Return runs created at or after this time (inclusive).
2320
21 format: date-time
22
2423- `"created_at[lt]": optional string`
2524
2625 Return runs created strictly before this time (exclusive).
2726
27 format: date-time
28
2829- `"created_at[lte]": optional string`
2930
3031 Return runs created at or before this time (inclusive).
3132
33 format: date-time
34
3235- `deployment_id: optional string`
3336
3437 Filter to a specific deployment. Omit to list across all deployments in the workspace. Filtering by a non-existent deployment_id returns 200 with empty data.
from line 44
4144
4245 Maximum results per page. Default 20, maximum 1000.
4346
47 format: int32
48
4449- `page: optional string`
4550
4651 Opaque pagination cursor. Pass next_page from the previous response. Invalid or expired cursors return 400.
from line 58
5358
5459 - `"manual"`
5560
56### Header Parameters
61### Headers
5762
5863- `"anthropic-beta": optional array of AnthropicBeta`
5964
from line 154
149154
150155 - `type: "agent"`
151156
152 - `"agent"`
153
154157 - `version: number`
155158
159 format: int32
160
156161 - `created_at: string`
157162
158163 A timestamp in RFC 3339 format
159164
165 format: date-time
166
160167 - `deployment_id: string`
161168
162169 ID of the deployment that produced this run.
from line 172
165172
166173 Why the run failed to create a session. The type identifies the failure; message is human-readable detail.
167174
168 - `BetaManagedAgentsEnvironmentArchivedRunError object { message, type }`
175 - `BetaManagedAgentsEnvironmentArchivedRunError object`
169176
170177 The deployment's environment was archived.
171178
from line 182
175182
176183 - `type: "environment_archived_error"`
177184
178 - `"environment_archived_error"`
185 - `BetaManagedAgentsAgentArchivedRunError object`
179186
180 - `BetaManagedAgentsAgentArchivedRunError object { message, type }`
181
182187 The deployment's agent was archived.
183188
184189 - `message: string`
from line 192
187192
188193 - `type: "agent_archived_error"`
189194
190 - `"agent_archived_error"`
195 - `BetaManagedAgentsEnvironmentNotFoundRunError object`
191196
192 - `BetaManagedAgentsEnvironmentNotFoundRunError object { message, type }`
193
194197 The deployment's environment no longer exists.
195198
196199 - `message: string`
from line 202
199202
200203 - `type: "environment_not_found_error"`
201204
202 - `"environment_not_found_error"`
205 - `BetaManagedAgentsVaultNotFoundRunError object`
203206
204 - `BetaManagedAgentsVaultNotFoundRunError object { message, type }`
205
206207 A vault referenced by the deployment no longer exists.
207208
208209 - `message: string`
from line 212
211212
212213 - `type: "vault_not_found_error"`
213214
214 - `"vault_not_found_error"`
215 - `BetaManagedAgentsVaultArchivedRunError object`
215216
216 - `BetaManagedAgentsVaultArchivedRunError object { message, type }`
217
218217 A vault referenced by the deployment is archived.
219218
220219 - `message: string`
from line 222
223222
224223 - `type: "vault_archived_error"`
225224
226 - `"vault_archived_error"`
225 - `BetaManagedAgentsFileNotFoundRunError object`
227226
228 - `BetaManagedAgentsFileNotFoundRunError object { message, type }`
229
230227 A file resource referenced by the deployment no longer exists.
231228
232229 - `message: string`
from line 232
235232
236233 - `type: "file_not_found_error"`
237234
238 - `"file_not_found_error"`
235 - `BetaManagedAgentsMemoryStoreArchivedRunError object`
239236
240 - `BetaManagedAgentsMemoryStoreArchivedRunError object { message, type }`
241
242237 A memory store referenced by the deployment is archived.
243238
244239 - `message: string`
from line 242
247242
248243 - `type: "memory_store_archived_error"`
249244
250 - `"memory_store_archived_error"`
245 - `BetaManagedAgentsSkillNotFoundRunError object`
251246
252 - `BetaManagedAgentsSkillNotFoundRunError object { message, type }`
253
254247 A skill referenced by the deployment's agent no longer exists.
255248
256249 - `message: string`
from line 252
259252
260253 - `type: "skill_not_found_error"`
261254
262 - `"skill_not_found_error"`
255 - `BetaManagedAgentsSessionResourceNotFoundRunError object`
263256
264 - `BetaManagedAgentsSessionResourceNotFoundRunError object { message, type }`
265
266257 A referenced resource no longer exists and its kind was not reported.
267258
268259 - `message: string`
from line 262
271262
272263 - `type: "session_resource_not_found_error"`
273264
274 - `"session_resource_not_found_error"`
265 - `BetaManagedAgentsWorkspaceArchivedRunError object`
275266
276 - `BetaManagedAgentsWorkspaceArchivedRunError object { message, type }`
277
278267 The deployment's workspace was archived.
279268
280269 - `message: string`
from line 272
283272
284273 - `type: "workspace_archived_error"`
285274
286 - `"workspace_archived_error"`
275 - `BetaManagedAgentsOrganizationDisabledRunError object`
287276
288 - `BetaManagedAgentsOrganizationDisabledRunError object { message, type }`
289
290277 The deployment's organization is disabled.
291278
292279 - `message: string`
from line 282
295282
296283 - `type: "organization_disabled_error"`
297284
298 - `"organization_disabled_error"`
285 - `BetaManagedAgentsSessionRateLimitedRunError object`
299286
300 - `BetaManagedAgentsSessionRateLimitedRunError object { message, type }`
301
302287 Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed.
303288
304289 - `message: string`
from line 292
307292
308293 - `type: "session_rate_limited_error"`
309294
310 - `"session_rate_limited_error"`
295 - `BetaManagedAgentsSessionCreationRejectedRunError object`
311296
312 - `BetaManagedAgentsSessionCreationRejectedRunError object { message, type }`
313
314297 The session create request was rejected with a non-retryable validation error.
315298
316299 - `message: string`
from line 302
319302
320303 - `type: "session_creation_rejected_error"`
321304
322 - `"session_creation_rejected_error"`
305 - `BetaManagedAgentsUnknownRunError object`
323306
324 - `BetaManagedAgentsUnknownRunError object { message, type }`
325
326307 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.
327308
328309 - `message: string`
from line 312
331312
332313 - `type: "unknown_error"`
333314
334 - `"unknown_error"`
315 - `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object`
335316
336 - `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object { message, type }`
337
338317 The deployment configures resources, but its environment is self-hosted and cannot mount them.
339318
340319 - `message: string`
from line 322
343322
344323 - `type: "self_hosted_resources_unsupported_error"`
345324
346 - `"self_hosted_resources_unsupported_error"`
325 - `BetaManagedAgentsMCPEgressBlockedRunError object`
347326
348 - `BetaManagedAgentsMCPEgressBlockedRunError object { message, type }`
349
350327 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
351328
352329 - `message: string`
from line 332
355332
356333 - `type: "mcp_egress_blocked_error"`
357334
358 - `"mcp_egress_blocked_error"`
359
360335 - `session_id: string or null`
361336
362337 Populated on success. Null on creation failure. Exactly one of session_id or error is non-null.
from line 340
365340
366341 Describes what triggered a deployment run, with trigger-specific metadata.
367342
368 - `BetaManagedAgentsScheduleTriggerContext object { scheduled_at, type }`
343 - `BetaManagedAgentsScheduleTriggerContext object`
369344
370345 The run was fired by the deployment's cron schedule.
371346
from line 348
373348
374349 A timestamp in RFC 3339 format
375350
351 format: date-time
352
376353 - `type: "schedule"`
377354
378 - `"schedule"`
355 - `BetaManagedAgentsManualTriggerContext object`
379356
380 - `BetaManagedAgentsManualTriggerContext object { type }`
381
382357 The run was started manually by creating a session directly against the deployment.
383358
384359 - `type: "manual"`
385360
386 - `"manual"`
387
388361 - `type: "deployment_run"`
389362
390 - `"deployment_run"`
391
392363- `next_page: optional string or null`
393364
394365 Opaque cursor for the next page. Null when no more results.
from line 366
395366
396367### Example
397368
398```http
369```bash
399370curl https://api.anthropic.com/v1/deployment_runs \
400371 -H 'anthropic-version: 2023-06-01' \
401372 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 373
402373 -H "X-Api-Key: $ANTHROPIC_API_KEY"
403374```
404375
405#### Response
376#### Response (200)
406377
407378```json
408379{
from line 405
434405
435406## Get Deployment Run
436407
437**get** `/v1/deployment_runs/{deployment_run_id}`
408**GET** `/v1/deployment_runs/{deployment_run_id}`
438409
439410Get Deployment Run
440411
441### Path Parameters
412### Path parameters
442413
443414- `deployment_run_id: string`
444415
445### Header Parameters
416### Headers
446417
447418- `"anthropic-beta": optional array of AnthropicBeta`
448419
from line 493
522493
523494### Returns
524495
525- `BetaManagedAgentsDeploymentRun object { id, agent, created_at, 5 more }`
496- `BetaManagedAgentsDeploymentRun object`
526497
527498 A persistent, append-only record of a single deployment execution. Records session creation success or failure — no session lifecycle tracking.
528499
from line 509
538509
539510 - `type: "agent"`
540511
541 - `"agent"`
542
543512 - `version: number`
544513
514 format: int32
515
545516 - `created_at: string`
546517
547518 A timestamp in RFC 3339 format
548519
520 format: date-time
521
549522 - `deployment_id: string`
550523
551524 ID of the deployment that produced this run.
from line 527
554527
555528 Why the run failed to create a session. The type identifies the failure; message is human-readable detail.
556529
557 - `BetaManagedAgentsEnvironmentArchivedRunError object { message, type }`
530 - `BetaManagedAgentsEnvironmentArchivedRunError object`
558531
559532 The deployment's environment was archived.
560533
from line 537
564537
565538 - `type: "environment_archived_error"`
566539
567 - `"environment_archived_error"`
540 - `BetaManagedAgentsAgentArchivedRunError object`
568541
569 - `BetaManagedAgentsAgentArchivedRunError object { message, type }`
570
571542 The deployment's agent was archived.
572543
573544 - `message: string`
from line 547
576547
577548 - `type: "agent_archived_error"`
578549
579 - `"agent_archived_error"`
550 - `BetaManagedAgentsEnvironmentNotFoundRunError object`
580551
581 - `BetaManagedAgentsEnvironmentNotFoundRunError object { message, type }`
582
583552 The deployment's environment no longer exists.
584553
585554 - `message: string`
from line 557
588557
589558 - `type: "environment_not_found_error"`
590559
591 - `"environment_not_found_error"`
560 - `BetaManagedAgentsVaultNotFoundRunError object`
592561
593 - `BetaManagedAgentsVaultNotFoundRunError object { message, type }`
594
595562 A vault referenced by the deployment no longer exists.
596563
597564 - `message: string`
from line 567
600567
601568 - `type: "vault_not_found_error"`
602569
603 - `"vault_not_found_error"`
570 - `BetaManagedAgentsVaultArchivedRunError object`
604571
605 - `BetaManagedAgentsVaultArchivedRunError object { message, type }`
606
607572 A vault referenced by the deployment is archived.
608573
609574 - `message: string`
from line 577
612577
613578 - `type: "vault_archived_error"`
614579
615 - `"vault_archived_error"`
580 - `BetaManagedAgentsFileNotFoundRunError object`
616581
617 - `BetaManagedAgentsFileNotFoundRunError object { message, type }`
618
619582 A file resource referenced by the deployment no longer exists.
620583
621584 - `message: string`
from line 587
624587
625588 - `type: "file_not_found_error"`
626589
627 - `"file_not_found_error"`
590 - `BetaManagedAgentsMemoryStoreArchivedRunError object`
628591
629 - `BetaManagedAgentsMemoryStoreArchivedRunError object { message, type }`
630
631592 A memory store referenced by the deployment is archived.
632593
633594 - `message: string`
from line 597
636597
637598 - `type: "memory_store_archived_error"`
638599
639 - `"memory_store_archived_error"`
600 - `BetaManagedAgentsSkillNotFoundRunError object`
640601
641 - `BetaManagedAgentsSkillNotFoundRunError object { message, type }`
642
643602 A skill referenced by the deployment's agent no longer exists.
644603
645604 - `message: string`
from line 607
648607
649608 - `type: "skill_not_found_error"`
650609
651 - `"skill_not_found_error"`
610 - `BetaManagedAgentsSessionResourceNotFoundRunError object`
652611
653 - `BetaManagedAgentsSessionResourceNotFoundRunError object { message, type }`
654
655612 A referenced resource no longer exists and its kind was not reported.
656613
657614 - `message: string`
from line 617
660617
661618 - `type: "session_resource_not_found_error"`
662619
663 - `"session_resource_not_found_error"`
620 - `BetaManagedAgentsWorkspaceArchivedRunError object`
664621
665 - `BetaManagedAgentsWorkspaceArchivedRunError object { message, type }`
666
667622 The deployment's workspace was archived.
668623
669624 - `message: string`
from line 627
672627
673628 - `type: "workspace_archived_error"`
674629
675 - `"workspace_archived_error"`
630 - `BetaManagedAgentsOrganizationDisabledRunError object`
676631
677 - `BetaManagedAgentsOrganizationDisabledRunError object { message, type }`
678
679632 The deployment's organization is disabled.
680633
681634 - `message: string`
from line 637
684637
685638 - `type: "organization_disabled_error"`
686639
687 - `"organization_disabled_error"`
640 - `BetaManagedAgentsSessionRateLimitedRunError object`
688641
689 - `BetaManagedAgentsSessionRateLimitedRunError object { message, type }`
690
691642 Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed.
692643
693644 - `message: string`
from line 647
696647
697648 - `type: "session_rate_limited_error"`
698649
699 - `"session_rate_limited_error"`
650 - `BetaManagedAgentsSessionCreationRejectedRunError object`
700651
701 - `BetaManagedAgentsSessionCreationRejectedRunError object { message, type }`
702
703652 The session create request was rejected with a non-retryable validation error.
704653
705654 - `message: string`
from line 657
708657
709658 - `type: "session_creation_rejected_error"`
710659
711 - `"session_creation_rejected_error"`
660 - `BetaManagedAgentsUnknownRunError object`
712661
713 - `BetaManagedAgentsUnknownRunError object { message, type }`
714
715662 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.
716663
717664 - `message: string`
from line 667
720667
721668 - `type: "unknown_error"`
722669
723 - `"unknown_error"`
670 - `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object`
724671
725 - `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object { message, type }`
726
727672 The deployment configures resources, but its environment is self-hosted and cannot mount them.
728673
729674 - `message: string`
from line 677
732677
733678 - `type: "self_hosted_resources_unsupported_error"`
734679
735 - `"self_hosted_resources_unsupported_error"`
680 - `BetaManagedAgentsMCPEgressBlockedRunError object`
736681
737 - `BetaManagedAgentsMCPEgressBlockedRunError object { message, type }`
738
739682 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
740683
741684 - `message: string`
from line 687
744687
745688 - `type: "mcp_egress_blocked_error"`
746689
747 - `"mcp_egress_blocked_error"`
748
749690 - `session_id: string or null`
750691
751692 Populated on success. Null on creation failure. Exactly one of session_id or error is non-null.
from line 695
754695
755696 Describes what triggered a deployment run, with trigger-specific metadata.
756697
757 - `BetaManagedAgentsScheduleTriggerContext object { scheduled_at, type }`
698 - `BetaManagedAgentsScheduleTriggerContext object`
758699
759700 The run was fired by the deployment's cron schedule.
760701
from line 703
762703
763704 A timestamp in RFC 3339 format
764705
706 format: date-time
707
765708 - `type: "schedule"`
766709
767 - `"schedule"`
710 - `BetaManagedAgentsManualTriggerContext object`
768711
769 - `BetaManagedAgentsManualTriggerContext object { type }`
770
771712 The run was started manually by creating a session directly against the deployment.
772713
773714 - `type: "manual"`
774715
775 - `"manual"`
776
777716 - `type: "deployment_run"`
778717
779 - `"deployment_run"`
780
781718### Example
782719
783```http
720```bash
784721curl https://api.anthropic.com/v1/deployment_runs/$DEPLOYMENT_RUN_ID \
785722 -H 'anthropic-version: 2023-06-01' \
786723 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 724
787724 -H "X-Api-Key: $ANTHROPIC_API_KEY"
788725```
789726
790#### Response
727#### Response (200)
791728
792729```json
793730{
from line 749
812749}
813750```
814751
815## Domain Types
752## Domain types
816753
817754### Beta Managed Agents Agent Archived Run Error
818755
819- `BetaManagedAgentsAgentArchivedRunError object { message, type }`
756- `BetaManagedAgentsAgentArchivedRunError object`
820757
821758 The deployment's agent was archived.
822759
from line 763
826763
827764 - `type: "agent_archived_error"`
828765
829 - `"agent_archived_error"`
830
831766### Beta Managed Agents Deployment Run
832767
833- `BetaManagedAgentsDeploymentRun object { id, agent, created_at, 5 more }`
768- `BetaManagedAgentsDeploymentRun object`
834769
835770 A persistent, append-only record of a single deployment execution. Records session creation success or failure — no session lifecycle tracking.
836771
from line 781
846781
847782 - `type: "agent"`
848783
849 - `"agent"`
850
851784 - `version: number`
852785
786 format: int32
787
853788 - `created_at: string`
854789
855790 A timestamp in RFC 3339 format
856791
792 format: date-time
793
857794 - `deployment_id: string`
858795
859796 ID of the deployment that produced this run.
from line 799
862799
863800 Why the run failed to create a session. The type identifies the failure; message is human-readable detail.
864801
865 - `BetaManagedAgentsEnvironmentArchivedRunError object { message, type }`
802 - `BetaManagedAgentsEnvironmentArchivedRunError object`
866803
867804 The deployment's environment was archived.
868805
from line 809
872809
873810 - `type: "environment_archived_error"`
874811
875 - `"environment_archived_error"`
812 - `BetaManagedAgentsAgentArchivedRunError object`
876813
877 - `BetaManagedAgentsAgentArchivedRunError object { message, type }`
878
879814 The deployment's agent was archived.
880815
881816 - `message: string`
from line 819
884819
885820 - `type: "agent_archived_error"`
886821
887 - `"agent_archived_error"`
822 - `BetaManagedAgentsEnvironmentNotFoundRunError object`
888823
889 - `BetaManagedAgentsEnvironmentNotFoundRunError object { message, type }`
890
891824 The deployment's environment no longer exists.
892825
893826 - `message: string`
from line 829
896829
897830 - `type: "environment_not_found_error"`
898831
899 - `"environment_not_found_error"`
832 - `BetaManagedAgentsVaultNotFoundRunError object`
900833
901 - `BetaManagedAgentsVaultNotFoundRunError object { message, type }`
902
903834 A vault referenced by the deployment no longer exists.
904835
905836 - `message: string`
from line 839
908839
909840 - `type: "vault_not_found_error"`
910841
911 - `"vault_not_found_error"`
842 - `BetaManagedAgentsVaultArchivedRunError object`
912843
913 - `BetaManagedAgentsVaultArchivedRunError object { message, type }`
914
915844 A vault referenced by the deployment is archived.
916845
917846 - `message: string`
from line 849
920849
921850 - `type: "vault_archived_error"`
922851
923 - `"vault_archived_error"`
852 - `BetaManagedAgentsFileNotFoundRunError object`
924853
925 - `BetaManagedAgentsFileNotFoundRunError object { message, type }`
926
927854 A file resource referenced by the deployment no longer exists.
928855
929856 - `message: string`
from line 859
932859
933860 - `type: "file_not_found_error"`
934861
935 - `"file_not_found_error"`
862 - `BetaManagedAgentsMemoryStoreArchivedRunError object`
936863
937 - `BetaManagedAgentsMemoryStoreArchivedRunError object { message, type }`
938
939864 A memory store referenced by the deployment is archived.
940865
941866 - `message: string`
from line 869
944869
945870 - `type: "memory_store_archived_error"`
946871
947 - `"memory_store_archived_error"`
872 - `BetaManagedAgentsSkillNotFoundRunError object`
948873
949 - `BetaManagedAgentsSkillNotFoundRunError object { message, type }`
950
951874 A skill referenced by the deployment's agent no longer exists.
952875
953876 - `message: string`
from line 879
956879
957880 - `type: "skill_not_found_error"`
958881
959 - `"skill_not_found_error"`
882 - `BetaManagedAgentsSessionResourceNotFoundRunError object`
960883
961 - `BetaManagedAgentsSessionResourceNotFoundRunError object { message, type }`
962
963884 A referenced resource no longer exists and its kind was not reported.
964885
965886 - `message: string`
from line 889
968889
969890 - `type: "session_resource_not_found_error"`
970891
971 - `"session_resource_not_found_error"`
892 - `BetaManagedAgentsWorkspaceArchivedRunError object`
972893
973 - `BetaManagedAgentsWorkspaceArchivedRunError object { message, type }`
974
975894 The deployment's workspace was archived.
976895
977896 - `message: string`
from line 899
980899
981900 - `type: "workspace_archived_error"`
982901
983 - `"workspace_archived_error"`
902 - `BetaManagedAgentsOrganizationDisabledRunError object`
984903
985 - `BetaManagedAgentsOrganizationDisabledRunError object { message, type }`
986
987904 The deployment's organization is disabled.
988905
989906 - `message: string`
from line 909
992909
993910 - `type: "organization_disabled_error"`
994911
995 - `"organization_disabled_error"`
912 - `BetaManagedAgentsSessionRateLimitedRunError object`
996913
997 - `BetaManagedAgentsSessionRateLimitedRunError object { message, type }`
998
999914 Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed.
1000915
1001916 - `message: string`
from line 919
1004919
1005920 - `type: "session_rate_limited_error"`
1006921
1007 - `"session_rate_limited_error"`
922 - `BetaManagedAgentsSessionCreationRejectedRunError object`
1008923
1009 - `BetaManagedAgentsSessionCreationRejectedRunError object { message, type }`
1010
1011924 The session create request was rejected with a non-retryable validation error.
1012925
1013926 - `message: string`
from line 929
1016929
1017930 - `type: "session_creation_rejected_error"`
1018931
1019 - `"session_creation_rejected_error"`
932 - `BetaManagedAgentsUnknownRunError object`
1020933
1021 - `BetaManagedAgentsUnknownRunError object { message, type }`
1022
1023934 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.
1024935
1025936 - `message: string`
from line 939
1028939
1029940 - `type: "unknown_error"`
1030941
1031 - `"unknown_error"`
942 - `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object`
1032943
1033 - `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object { message, type }`
1034
1035944 The deployment configures resources, but its environment is self-hosted and cannot mount them.
1036945
1037946 - `message: string`
from line 949
1040949
1041950 - `type: "self_hosted_resources_unsupported_error"`
1042951
1043 - `"self_hosted_resources_unsupported_error"`
952 - `BetaManagedAgentsMCPEgressBlockedRunError object`
1044953
1045 - `BetaManagedAgentsMCPEgressBlockedRunError object { message, type }`
1046
1047954 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
1048955
1049956 - `message: string`
from line 959
1052959
1053960 - `type: "mcp_egress_blocked_error"`
1054961
1055 - `"mcp_egress_blocked_error"`
1056
1057962 - `session_id: string or null`
1058963
1059964 Populated on success. Null on creation failure. Exactly one of session_id or error is non-null.
from line 967
1062967
1063968 Describes what triggered a deployment run, with trigger-specific metadata.
1064969
1065 - `BetaManagedAgentsScheduleTriggerContext object { scheduled_at, type }`
970 - `BetaManagedAgentsScheduleTriggerContext object`
1066971
1067972 The run was fired by the deployment's cron schedule.
1068973
from line 975
1070975
1071976 A timestamp in RFC 3339 format
1072977
978 format: date-time
979
1073980 - `type: "schedule"`
1074981
1075 - `"schedule"`
982 - `BetaManagedAgentsManualTriggerContext object`
1076983
1077 - `BetaManagedAgentsManualTriggerContext object { type }`
1078
1079984 The run was started manually by creating a session directly against the deployment.
1080985
1081986 - `type: "manual"`
1082987
1083 - `"manual"`
1084
1085988 - `type: "deployment_run"`
1086989
1087 - `"deployment_run"`
1088
1089990### Beta Managed Agents Environment Archived Run Error
1090991
1091- `BetaManagedAgentsEnvironmentArchivedRunError object { message, type }`
992- `BetaManagedAgentsEnvironmentArchivedRunError object`
1092993
1093994 The deployment's environment was archived.
1094995
from line 999
1098999
10991000 - `type: "environment_archived_error"`
11001001
1101 - `"environment_archived_error"`
1102
11031002### Beta Managed Agents Environment Not Found Run Error
11041003
1105- `BetaManagedAgentsEnvironmentNotFoundRunError object { message, type }`
1004- `BetaManagedAgentsEnvironmentNotFoundRunError object`
11061005
11071006 The deployment's environment no longer exists.
11081007
from line 1011
11121011
11131012 - `type: "environment_not_found_error"`
11141013
1115 - `"environment_not_found_error"`
1116
11171014### Beta Managed Agents File Not Found Run Error
11181015
1119- `BetaManagedAgentsFileNotFoundRunError object { message, type }`
1016- `BetaManagedAgentsFileNotFoundRunError object`
11201017
11211018 A file resource referenced by the deployment no longer exists.
11221019
from line 1023
11261023
11271024 - `type: "file_not_found_error"`
11281025
1129 - `"file_not_found_error"`
1130
11311026### Beta Managed Agents Manual Trigger Context
11321027
1133- `BetaManagedAgentsManualTriggerContext object { type }`
1028- `BetaManagedAgentsManualTriggerContext object`
11341029
11351030 The run was started manually by creating a session directly against the deployment.
11361031
11371032 - `type: "manual"`
11381033
1139 - `"manual"`
1140
11411034### Beta Managed Agents MCP Egress Blocked Run Error
11421035
1143- `BetaManagedAgentsMCPEgressBlockedRunError object { message, type }`
1036- `BetaManagedAgentsMCPEgressBlockedRunError object`
11441037
11451038 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
11461039
from line 1043
11501043
11511044 - `type: "mcp_egress_blocked_error"`
11521045
1153 - `"mcp_egress_blocked_error"`
1154
11551046### Beta Managed Agents Memory Store Archived Run Error
11561047
1157- `BetaManagedAgentsMemoryStoreArchivedRunError object { message, type }`
1048- `BetaManagedAgentsMemoryStoreArchivedRunError object`
11581049
11591050 A memory store referenced by the deployment is archived.
11601051
from line 1055
11641055
11651056 - `type: "memory_store_archived_error"`
11661057
1167 - `"memory_store_archived_error"`
1168
11691058### Beta Managed Agents Organization Disabled Run Error
11701059
1171- `BetaManagedAgentsOrganizationDisabledRunError object { message, type }`
1060- `BetaManagedAgentsOrganizationDisabledRunError object`
11721061
11731062 The deployment's organization is disabled.
11741063
from line 1067
11781067
11791068 - `type: "organization_disabled_error"`
11801069
1181 - `"organization_disabled_error"`
1182
11831070### Beta Managed Agents Schedule Trigger Context
11841071
1185- `BetaManagedAgentsScheduleTriggerContext object { scheduled_at, type }`
1072- `BetaManagedAgentsScheduleTriggerContext object`
11861073
11871074 The run was fired by the deployment's cron schedule.
11881075
from line 1077
11901077
11911078 A timestamp in RFC 3339 format
11921079
1080 format: date-time
1081
11931082 - `type: "schedule"`
11941083
1195 - `"schedule"`
1196
11971084### Beta Managed Agents Self Hosted Resources Unsupported Run Error
11981085
1199- `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object { message, type }`
1086- `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object`
12001087
12011088 The deployment configures resources, but its environment is self-hosted and cannot mount them.
12021089
from line 1093
12061093
12071094 - `type: "self_hosted_resources_unsupported_error"`
12081095
1209 - `"self_hosted_resources_unsupported_error"`
1210
12111096### Beta Managed Agents Session Creation Rejected Run Error
12121097
1213- `BetaManagedAgentsSessionCreationRejectedRunError object { message, type }`
1098- `BetaManagedAgentsSessionCreationRejectedRunError object`
12141099
12151100 The session create request was rejected with a non-retryable validation error.
12161101
from line 1105
12201105
12211106 - `type: "session_creation_rejected_error"`
12221107
1223 - `"session_creation_rejected_error"`
1224
12251108### Beta Managed Agents Session Rate Limited Run Error
12261109
1227- `BetaManagedAgentsSessionRateLimitedRunError object { message, type }`
1110- `BetaManagedAgentsSessionRateLimitedRunError object`
12281111
12291112 Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed.
12301113
from line 1117
12341117
12351118 - `type: "session_rate_limited_error"`
12361119
1237 - `"session_rate_limited_error"`
1238
12391120### Beta Managed Agents Session Resource Not Found Run Error
12401121
1241- `BetaManagedAgentsSessionResourceNotFoundRunError object { message, type }`
1122- `BetaManagedAgentsSessionResourceNotFoundRunError object`
12421123
12431124 A referenced resource no longer exists and its kind was not reported.
12441125
from line 1129
12481129
12491130 - `type: "session_resource_not_found_error"`
12501131
1251 - `"session_resource_not_found_error"`
1252
12531132### Beta Managed Agents Skill Not Found Run Error
12541133
1255- `BetaManagedAgentsSkillNotFoundRunError object { message, type }`
1134- `BetaManagedAgentsSkillNotFoundRunError object`
12561135
12571136 A skill referenced by the deployment's agent no longer exists.
12581137
from line 1141
12621141
12631142 - `type: "skill_not_found_error"`
12641143
1265 - `"skill_not_found_error"`
1266
12671144### Beta Managed Agents Trigger Context
12681145
12691146- `BetaManagedAgentsTriggerContext = BetaManagedAgentsScheduleTriggerContext or BetaManagedAgentsManualTriggerContext`
from line 1147
12701147
12711148 Describes what triggered a deployment run, with trigger-specific metadata.
12721149
1273 - `BetaManagedAgentsScheduleTriggerContext object { scheduled_at, type }`
1150 - `BetaManagedAgentsScheduleTriggerContext object`
12741151
12751152 The run was fired by the deployment's cron schedule.
12761153
from line 1155
12781155
12791156 A timestamp in RFC 3339 format
12801157
1158 format: date-time
1159
12811160 - `type: "schedule"`
12821161
1283 - `"schedule"`
1162 - `BetaManagedAgentsManualTriggerContext object`
12841163
1285 - `BetaManagedAgentsManualTriggerContext object { type }`
1286
12871164 The run was started manually by creating a session directly against the deployment.
12881165
12891166 - `type: "manual"`
12901167
1291 - `"manual"`
1292
12931168### Beta Managed Agents Trigger Type
12941169
12951170- `BetaManagedAgentsTriggerType = "schedule" or "manual"`
from line 1177
13021177
13031178### Beta Managed Agents Unknown Run Error
13041179
1305- `BetaManagedAgentsUnknownRunError object { message, type }`
1180- `BetaManagedAgentsUnknownRunError object`
13061181
13071182 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.
13081183
from line 1187
13121187
13131188 - `type: "unknown_error"`
13141189
1315 - `"unknown_error"`
1316
13171190### Beta Managed Agents Vault Archived Run Error
13181191
1319- `BetaManagedAgentsVaultArchivedRunError object { message, type }`
1192- `BetaManagedAgentsVaultArchivedRunError object`
13201193
13211194 A vault referenced by the deployment is archived.
13221195
from line 1199
13261199
13271200 - `type: "vault_archived_error"`
13281201
1329 - `"vault_archived_error"`
1330
13311202### Beta Managed Agents Vault Not Found Run Error
13321203
1333- `BetaManagedAgentsVaultNotFoundRunError object { message, type }`
1204- `BetaManagedAgentsVaultNotFoundRunError object`
13341205
13351206 A vault referenced by the deployment no longer exists.
13361207
from line 1211
13401211
13411212 - `type: "vault_not_found_error"`
13421213
1343 - `"vault_not_found_error"`
1344
13451214### Beta Managed Agents Workspace Archived Run Error
13461215
1347- `BetaManagedAgentsWorkspaceArchivedRunError object { message, type }`
1216- `BetaManagedAgentsWorkspaceArchivedRunError object`
13481217
13491218 The deployment's workspace was archived.
13501219
from line 1222
13531222 Human-readable error description.
13541223
13551224 - `type: "workspace_archived_error"`
1356
1357 - `"workspace_archived_error"`
13581225
api/beta/deployment_runs/list Changed · +44 / -73 lines
# List Deployment Runs ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List Deployment Runs ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: List Deployment Runs
3url: https://platform.claude.com/docs/en/api/beta/deployment_runs/list
4---
1# List Deployment Runs
52
6## List Deployment Runs
3**GET** `/v1/deployment_runs`
74
8**get** `/v1/deployment_runs`
9
105List Deployment Runs
116
12### Query Parameters
7## Query parameters
138
149- `"created_at[gt]": optional string`
1510
1611 Return runs created strictly after this time (exclusive).
1712
13 format: date-time
14
1815- `"created_at[gte]": optional string`
1916
2017 Return runs created at or after this time (inclusive).
2118
19 format: date-time
20
2221- `"created_at[lt]": optional string`
2322
2423 Return runs created strictly before this time (exclusive).
2524
25 format: date-time
26
2627- `"created_at[lte]": optional string`
2728
2829 Return runs created at or before this time (inclusive).
2930
31 format: date-time
32
3033- `deployment_id: optional string`
3134
3235 Filter to a specific deployment. Omit to list across all deployments in the workspace. Filtering by a non-existent deployment_id returns 200 with empty data.
from line 42
3942
4043 Maximum results per page. Default 20, maximum 1000.
4144
45 format: int32
46
4247- `page: optional string`
4348
4449 Opaque pagination cursor. Pass next_page from the previous response. Invalid or expired cursors return 400.
from line 56
5156
5257 - `"manual"`
5358
54### Header Parameters
59## Headers
5560
5661- `"anthropic-beta": optional array of AnthropicBeta`
5762
from line 134
129134
130135 - `"mid-conversation-tool-changes-2026-07-01"`
131136
132### Returns
137## Returns
133138
134139- `data: array of BetaManagedAgentsDeploymentRun`
135140
from line 152
147152
148153 - `type: "agent"`
149154
150 - `"agent"`
151
152155 - `version: number`
153156
157 format: int32
158
154159 - `created_at: string`
155160
156161 A timestamp in RFC 3339 format
157162
163 format: date-time
164
158165 - `deployment_id: string`
159166
160167 ID of the deployment that produced this run.
from line 170
163170
164171 Why the run failed to create a session. The type identifies the failure; message is human-readable detail.
165172
166 - `BetaManagedAgentsEnvironmentArchivedRunError object { message, type }`
173 - `BetaManagedAgentsEnvironmentArchivedRunError object`
167174
168175 The deployment's environment was archived.
169176
from line 180
173180
174181 - `type: "environment_archived_error"`
175182
176 - `"environment_archived_error"`
183 - `BetaManagedAgentsAgentArchivedRunError object`
177184
178 - `BetaManagedAgentsAgentArchivedRunError object { message, type }`
179
180185 The deployment's agent was archived.
181186
182187 - `message: string`
from line 190
185190
186191 - `type: "agent_archived_error"`
187192
188 - `"agent_archived_error"`
193 - `BetaManagedAgentsEnvironmentNotFoundRunError object`
189194
190 - `BetaManagedAgentsEnvironmentNotFoundRunError object { message, type }`
191
192195 The deployment's environment no longer exists.
193196
194197 - `message: string`
from line 200
197200
198201 - `type: "environment_not_found_error"`
199202
200 - `"environment_not_found_error"`
203 - `BetaManagedAgentsVaultNotFoundRunError object`
201204
202 - `BetaManagedAgentsVaultNotFoundRunError object { message, type }`
203
204205 A vault referenced by the deployment no longer exists.
205206
206207 - `message: string`
from line 210
209210
210211 - `type: "vault_not_found_error"`
211212
212 - `"vault_not_found_error"`
213 - `BetaManagedAgentsVaultArchivedRunError object`
213214
214 - `BetaManagedAgentsVaultArchivedRunError object { message, type }`
215
216215 A vault referenced by the deployment is archived.
217216
218217 - `message: string`
from line 220
221220
222221 - `type: "vault_archived_error"`
223222
224 - `"vault_archived_error"`
223 - `BetaManagedAgentsFileNotFoundRunError object`
225224
226 - `BetaManagedAgentsFileNotFoundRunError object { message, type }`
227
228225 A file resource referenced by the deployment no longer exists.
229226
230227 - `message: string`
from line 230
233230
234231 - `type: "file_not_found_error"`
235232
236 - `"file_not_found_error"`
233 - `BetaManagedAgentsMemoryStoreArchivedRunError object`
237234
238 - `BetaManagedAgentsMemoryStoreArchivedRunError object { message, type }`
239
240235 A memory store referenced by the deployment is archived.
241236
242237 - `message: string`
from line 240
245240
246241 - `type: "memory_store_archived_error"`
247242
248 - `"memory_store_archived_error"`
243 - `BetaManagedAgentsSkillNotFoundRunError object`
249244
250 - `BetaManagedAgentsSkillNotFoundRunError object { message, type }`
251
252245 A skill referenced by the deployment's agent no longer exists.
253246
254247 - `message: string`
from line 250
257250
258251 - `type: "skill_not_found_error"`
259252
260 - `"skill_not_found_error"`
253 - `BetaManagedAgentsSessionResourceNotFoundRunError object`
261254
262 - `BetaManagedAgentsSessionResourceNotFoundRunError object { message, type }`
263
264255 A referenced resource no longer exists and its kind was not reported.
265256
266257 - `message: string`
from line 260
269260
270261 - `type: "session_resource_not_found_error"`
271262
272 - `"session_resource_not_found_error"`
263 - `BetaManagedAgentsWorkspaceArchivedRunError object`
273264
274 - `BetaManagedAgentsWorkspaceArchivedRunError object { message, type }`
275
276265 The deployment's workspace was archived.
277266
278267 - `message: string`
from line 270
281270
282271 - `type: "workspace_archived_error"`
283272
284 - `"workspace_archived_error"`
273 - `BetaManagedAgentsOrganizationDisabledRunError object`
285274
286 - `BetaManagedAgentsOrganizationDisabledRunError object { message, type }`
287
288275 The deployment's organization is disabled.
289276
290277 - `message: string`
from line 280
293280
294281 - `type: "organization_disabled_error"`
295282
296 - `"organization_disabled_error"`
283 - `BetaManagedAgentsSessionRateLimitedRunError object`
297284
298 - `BetaManagedAgentsSessionRateLimitedRunError object { message, type }`
299
300285 Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed.
301286
302287 - `message: string`
from line 290
305290
306291 - `type: "session_rate_limited_error"`
307292
308 - `"session_rate_limited_error"`
293 - `BetaManagedAgentsSessionCreationRejectedRunError object`
309294
310 - `BetaManagedAgentsSessionCreationRejectedRunError object { message, type }`
311
312295 The session create request was rejected with a non-retryable validation error.
313296
314297 - `message: string`
from line 300
317300
318301 - `type: "session_creation_rejected_error"`
319302
320 - `"session_creation_rejected_error"`
303 - `BetaManagedAgentsUnknownRunError object`
321304
322 - `BetaManagedAgentsUnknownRunError object { message, type }`
323
324305 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.
325306
326307 - `message: string`
from line 310
329310
330311 - `type: "unknown_error"`
331312
332 - `"unknown_error"`
313 - `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object`
333314
334 - `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object { message, type }`
335
336315 The deployment configures resources, but its environment is self-hosted and cannot mount them.
337316
338317 - `message: string`
from line 320
341320
342321 - `type: "self_hosted_resources_unsupported_error"`
343322
344 - `"self_hosted_resources_unsupported_error"`
323 - `BetaManagedAgentsMCPEgressBlockedRunError object`
345324
346 - `BetaManagedAgentsMCPEgressBlockedRunError object { message, type }`
347
348325 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
349326
350327 - `message: string`
from line 330
353330
354331 - `type: "mcp_egress_blocked_error"`
355332
356 - `"mcp_egress_blocked_error"`
357
358333 - `session_id: string or null`
359334
360335 Populated on success. Null on creation failure. Exactly one of session_id or error is non-null.
from line 338
363338
364339 Describes what triggered a deployment run, with trigger-specific metadata.
365340
366 - `BetaManagedAgentsScheduleTriggerContext object { scheduled_at, type }`
341 - `BetaManagedAgentsScheduleTriggerContext object`
367342
368343 The run was fired by the deployment's cron schedule.
369344
from line 346
371346
372347 A timestamp in RFC 3339 format
373348
349 format: date-time
350
374351 - `type: "schedule"`
375352
376 - `"schedule"`
353 - `BetaManagedAgentsManualTriggerContext object`
377354
378 - `BetaManagedAgentsManualTriggerContext object { type }`
379
380355 The run was started manually by creating a session directly against the deployment.
381356
382357 - `type: "manual"`
383358
384 - `"manual"`
385
386359 - `type: "deployment_run"`
387360
388 - `"deployment_run"`
389
390361- `next_page: optional string or null`
391362
392363 Opaque cursor for the next page. Null when no more results.
393364
394### Example
365## Example
395366
396```http
367```bash
397368curl https://api.anthropic.com/v1/deployment_runs \
398369 -H 'anthropic-version: 2023-06-01' \
399370 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 371
400371 -H "X-Api-Key: $ANTHROPIC_API_KEY"
401372```
402373
403#### Response
374### Response (200)
404375
405376```json
406377{
api/beta/deployment_runs/retrieve Changed · +36 / -75 lines
# Get Deployment Run ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Get Deployment Run ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Get Deployment Run
3url: https://platform.claude.com/docs/en/api/beta/deployment_runs/retrieve
4---
1# Get Deployment Run
52
6## Get Deployment Run
3**GET** `/v1/deployment_runs/{deployment_run_id}`
74
8**get** `/v1/deployment_runs/{deployment_run_id}`
9
105Get Deployment Run
116
12### Path Parameters
7## Path parameters
138
149- `deployment_run_id: string`
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Returns
89## Returns
9590
96- `BetaManagedAgentsDeploymentRun object { id, agent, created_at, 5 more }`
91- `BetaManagedAgentsDeploymentRun object`
9792
9893 A persistent, append-only record of a single deployment execution. Records session creation success or failure — no session lifecycle tracking.
9994
from line 104
109104
110105 - `type: "agent"`
111106
112 - `"agent"`
113
114107 - `version: number`
115108
109 format: int32
110
116111 - `created_at: string`
117112
118113 A timestamp in RFC 3339 format
119114
115 format: date-time
116
120117 - `deployment_id: string`
121118
122119 ID of the deployment that produced this run.
from line 122
125122
126123 Why the run failed to create a session. The type identifies the failure; message is human-readable detail.
127124
128 - `BetaManagedAgentsEnvironmentArchivedRunError object { message, type }`
125 - `BetaManagedAgentsEnvironmentArchivedRunError object`
129126
130127 The deployment's environment was archived.
131128
from line 132
135132
136133 - `type: "environment_archived_error"`
137134
138 - `"environment_archived_error"`
135 - `BetaManagedAgentsAgentArchivedRunError object`
139136
140 - `BetaManagedAgentsAgentArchivedRunError object { message, type }`
141
142137 The deployment's agent was archived.
143138
144139 - `message: string`
from line 142
147142
148143 - `type: "agent_archived_error"`
149144
150 - `"agent_archived_error"`
145 - `BetaManagedAgentsEnvironmentNotFoundRunError object`
151146
152 - `BetaManagedAgentsEnvironmentNotFoundRunError object { message, type }`
153
154147 The deployment's environment no longer exists.
155148
156149 - `message: string`
from line 152
159152
160153 - `type: "environment_not_found_error"`
161154
162 - `"environment_not_found_error"`
155 - `BetaManagedAgentsVaultNotFoundRunError object`
163156
164 - `BetaManagedAgentsVaultNotFoundRunError object { message, type }`
165
166157 A vault referenced by the deployment no longer exists.
167158
168159 - `message: string`
from line 162
171162
172163 - `type: "vault_not_found_error"`
173164
174 - `"vault_not_found_error"`
165 - `BetaManagedAgentsVaultArchivedRunError object`
175166
176 - `BetaManagedAgentsVaultArchivedRunError object { message, type }`
177
178167 A vault referenced by the deployment is archived.
179168
180169 - `message: string`
from line 172
183172
184173 - `type: "vault_archived_error"`
185174
186 - `"vault_archived_error"`
175 - `BetaManagedAgentsFileNotFoundRunError object`
187176
188 - `BetaManagedAgentsFileNotFoundRunError object { message, type }`
189
190177 A file resource referenced by the deployment no longer exists.
191178
192179 - `message: string`
from line 182
195182
196183 - `type: "file_not_found_error"`
197184
198 - `"file_not_found_error"`
185 - `BetaManagedAgentsMemoryStoreArchivedRunError object`
199186
200 - `BetaManagedAgentsMemoryStoreArchivedRunError object { message, type }`
201
202187 A memory store referenced by the deployment is archived.
203188
204189 - `message: string`
from line 192
207192
208193 - `type: "memory_store_archived_error"`
209194
210 - `"memory_store_archived_error"`
195 - `BetaManagedAgentsSkillNotFoundRunError object`
211196
212 - `BetaManagedAgentsSkillNotFoundRunError object { message, type }`
213
214197 A skill referenced by the deployment's agent no longer exists.
215198
216199 - `message: string`
from line 202
219202
220203 - `type: "skill_not_found_error"`
221204
222 - `"skill_not_found_error"`
205 - `BetaManagedAgentsSessionResourceNotFoundRunError object`
223206
224 - `BetaManagedAgentsSessionResourceNotFoundRunError object { message, type }`
225
226207 A referenced resource no longer exists and its kind was not reported.
227208
228209 - `message: string`
from line 212
231212
232213 - `type: "session_resource_not_found_error"`
233214
234 - `"session_resource_not_found_error"`
215 - `BetaManagedAgentsWorkspaceArchivedRunError object`
235216
236 - `BetaManagedAgentsWorkspaceArchivedRunError object { message, type }`
237
238217 The deployment's workspace was archived.
239218
240219 - `message: string`
from line 222
243222
244223 - `type: "workspace_archived_error"`
245224
246 - `"workspace_archived_error"`
225 - `BetaManagedAgentsOrganizationDisabledRunError object`
247226
248 - `BetaManagedAgentsOrganizationDisabledRunError object { message, type }`
249
250227 The deployment's organization is disabled.
251228
252229 - `message: string`
from line 232
255232
256233 - `type: "organization_disabled_error"`
257234
258 - `"organization_disabled_error"`
235 - `BetaManagedAgentsSessionRateLimitedRunError object`
259236
260 - `BetaManagedAgentsSessionRateLimitedRunError object { message, type }`
261
262237 Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed.
263238
264239 - `message: string`
from line 242
267242
268243 - `type: "session_rate_limited_error"`
269244
270 - `"session_rate_limited_error"`
245 - `BetaManagedAgentsSessionCreationRejectedRunError object`
271246
272 - `BetaManagedAgentsSessionCreationRejectedRunError object { message, type }`
273
274247 The session create request was rejected with a non-retryable validation error.
275248
276249 - `message: string`
from line 252
279252
280253 - `type: "session_creation_rejected_error"`
281254
282 - `"session_creation_rejected_error"`
255 - `BetaManagedAgentsUnknownRunError object`
283256
284 - `BetaManagedAgentsUnknownRunError object { message, type }`
285
286257 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.
287258
288259 - `message: string`
from line 262
291262
292263 - `type: "unknown_error"`
293264
294 - `"unknown_error"`
265 - `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object`
295266
296 - `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object { message, type }`
297
298267 The deployment configures resources, but its environment is self-hosted and cannot mount them.
299268
300269 - `message: string`
from line 272
303272
304273 - `type: "self_hosted_resources_unsupported_error"`
305274
306 - `"self_hosted_resources_unsupported_error"`
275 - `BetaManagedAgentsMCPEgressBlockedRunError object`
307276
308 - `BetaManagedAgentsMCPEgressBlockedRunError object { message, type }`
309
310277 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
311278
312279 - `message: string`
from line 282
315282
316283 - `type: "mcp_egress_blocked_error"`
317284
318 - `"mcp_egress_blocked_error"`
319
320285 - `session_id: string or null`
321286
322287 Populated on success. Null on creation failure. Exactly one of session_id or error is non-null.
from line 290
325290
326291 Describes what triggered a deployment run, with trigger-specific metadata.
327292
328 - `BetaManagedAgentsScheduleTriggerContext object { scheduled_at, type }`
293 - `BetaManagedAgentsScheduleTriggerContext object`
329294
330295 The run was fired by the deployment's cron schedule.
331296
from line 298
333298
334299 A timestamp in RFC 3339 format
335300
301 format: date-time
302
336303 - `type: "schedule"`
337304
338 - `"schedule"`
305 - `BetaManagedAgentsManualTriggerContext object`
339306
340 - `BetaManagedAgentsManualTriggerContext object { type }`
341
342307 The run was started manually by creating a session directly against the deployment.
343308
344309 - `type: "manual"`
345310
346 - `"manual"`
347
348311 - `type: "deployment_run"`
349312
350 - `"deployment_run"`
313## Example
351314
352### Example
353
354```http
315```bash
355316curl https://api.anthropic.com/v1/deployment_runs/$DEPLOYMENT_RUN_ID \
356317 -H 'anthropic-version: 2023-06-01' \
357318 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 319
358319 -H "X-Api-Key: $ANTHROPIC_API_KEY"
359320```
360321
361#### Response
322### Response (200)
362323
363324```json
364325{
api/beta/deployments Changed · +1092 / -1643 lines
### Headers ### Body parameters #### Response (200) ### Query parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ### Path parameters ### Headers ### Body parameters #### Response (200) ### Path parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ## Domain types ### Header Parameters ### Body Parameters #### Response ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters ### Body Parameters #### Response ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ## Domain Types
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 1
1---
2title: Deployments
3url: https://platform.claude.com/docs/en/api/beta/deployments
4---
5
61# Deployments
72
83## Create Deployment
94
10**post** `/v1/deployments`
5**POST** `/v1/deployments`
116
127Create Deployment
138
14### Header Parameters
9### Headers
1510
1611- `"anthropic-beta": optional array of AnthropicBeta`
1712
from line 84
8984
9085 - `"mid-conversation-tool-changes-2026-07-01"`
9186
92### Body Parameters
87### Body parameters
9388
9489- `agent: string or BetaManagedAgentsAgentParams`
9590
from line 92
9792
9893 - `string`
9994
100 - `BetaManagedAgentsAgentParams object { id, type, version }`
95 - `BetaManagedAgentsAgentParams object`
10196
10297 Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version
10398
from line 100
105100
106101 The `agent` ID.
107102
103 minLength: 1, maxLength: 128
104
108105 - `type: "agent"`
109106
110 - `"agent"`
111
112107 - `version: optional number`
113108
114109 The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.
115110
111 format: int32
112
116113- `environment_id: string`
117114
118115 ID of the `environment` defining the container configuration for sessions created from this deployment.
119116
117 minLength: 1, maxLength: 128
118
120119- `initial_events: array of BetaManagedAgentsDeploymentInitialEventParams`
121120
122121 Events to send to each session immediately after creation. At least 1, maximum 50.
123122
124 - `BetaManagedAgentsUserMessageEventParams object { content, type }`
123 - `BetaManagedAgentsUserMessageEventParams object`
125124
126125 Parameters for sending a user message to the session.
127126
from line 128
129128
130129 Array of content blocks for the user message.
131130
132 - `BetaManagedAgentsTextBlock object { text, type }`
131 - `BetaManagedAgentsTextBlock object`
133132
134133 Regular text content.
135134
from line 136
137136
138137 The text content.
139138
139 minLength: 1
140
140141 - `type: "text"`
141142
142 - `"text"`
143
144 - `BetaManagedAgentsImageBlock object { source, type }`
143 - `BetaManagedAgentsImageBlock object`
145144
146145 Image content specified directly as base64 data or as a reference via a URL.
147146
from line 148
149148
150149 Union type for image source variants.
151150
152 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
151 - `BetaManagedAgentsBase64ImageSource object`
153152
154153 Base64-encoded image data.
155154
from line 156
157156
158157 Base64-encoded image data.
159158
159 minLength: 1
160
160161 - `media_type: string`
161162
162163 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
163164
165 minLength: 1
166
164167 - `type: "base64"`
165168
166 - `"base64"`
167
168 - `BetaManagedAgentsURLImageSource object { type, url }`
169 - `BetaManagedAgentsURLImageSource object`
169170
170171 Image referenced by URL.
171172
172173 - `type: "url"`
173174
174 - `"url"`
175
176175 - `url: string`
177176
178177 URL of the image to fetch.
179178
180 - `BetaManagedAgentsFileImageSource object { file_id, type }`
179 minLength: 1
180
181 - `BetaManagedAgentsFileImageSource object`
181182
182183 Image referenced by file ID.
183184
from line 186
185186
186187 ID of a previously uploaded file.
187188
189 minLength: 1
190
188191 - `type: "file"`
189192
190 - `"file"`
191
192193 - `type: "image"`
193194
194 - `"image"`
195
196 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
195 - `BetaManagedAgentsDocumentBlock object`
197196
198197 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
199198
from line 200
201200
202201 Union type for document source variants.
203202
204 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
203 - `BetaManagedAgentsBase64DocumentSource object`
205204
206205 Base64-encoded document data.
207206
from line 208
209208
210209 Base64-encoded document data.
211210
211 minLength: 1
212
212213 - `media_type: string`
213214
214215 MIME type of the document (e.g., "application/pdf").
215216
217 minLength: 1
218
216219 - `type: "base64"`
217220
218 - `"base64"`
219
220 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
221 - `BetaManagedAgentsPlainTextDocumentSource object`
221222
222223 Plain text document content.
223224
from line 226
225226
226227 The plain text content.
227228
229 minLength: 1
230
228231 - `media_type: "text/plain"`
229232
230233 MIME type of the text content. Must be "text/plain".
231234
232 - `"text/plain"`
233
234235 - `type: "text"`
235236
236 - `"text"`
237
238 - `BetaManagedAgentsURLDocumentSource object { type, url }`
237 - `BetaManagedAgentsURLDocumentSource object`
239238
240239 Document referenced by URL.
241240
242241 - `type: "url"`
243242
244 - `"url"`
245
246243 - `url: string`
247244
248245 URL of the document to fetch.
249246
250 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
247 minLength: 1
248
249 - `BetaManagedAgentsFileDocumentSource object`
251250
252251 Document referenced by file ID.
253252
from line 254
255254
256255 ID of a previously uploaded file.
257256
257 minLength: 1
258
258259 - `type: "file"`
259260
260 - `"file"`
261
262261 - `type: "document"`
263262
264 - `"document"`
265
266263 - `context: optional string or null`
267264
268265 Additional context about the document for the model.
from line 268
271268
272269 The title of the document.
273270
274 - `BetaManagedAgentsRedactedBlock object { type }`
271 - `BetaManagedAgentsRedactedBlock object`
275272
276273 Placeholder for content withheld by Anthropic model policy.
277274
278275 - `type: "redacted"`
279276
280 - `"redacted"`
281
282277 - `type: "user.message"`
283278
284 - `"user.message"`
285
286 - `BetaManagedAgentsUserDefineOutcomeEventParams object { description, rubric, type, max_iterations }`
279 - `BetaManagedAgentsUserDefineOutcomeEventParams object`
287280
288281 Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.
289282
from line 288
295288
296289 Rubric for grading the quality of an outcome.
297290
298 - `BetaManagedAgentsFileRubricParams object { file_id, type }`
291 - `BetaManagedAgentsFileRubricParams object`
299292
300293 Rubric referenced by a file uploaded via the Files API.
301294
from line 298
305298
306299 - `type: "file"`
307300
308 - `"file"`
309
310 - `BetaManagedAgentsTextRubricParams object { content, type }`
301 - `BetaManagedAgentsTextRubricParams object`
311302
312303 Rubric content provided inline as text.
313304
from line 306
315306
316307 Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.
317308
309 maxLength: 262144
310
318311 - `type: "text"`
319312
320 - `"text"`
321
322313 - `type: "user.define_outcome"`
323314
324 - `"user.define_outcome"`
325
326315 - `max_iterations: optional number or null`
327316
328317 Eval→revision cycles before giving up. Default 3, max 20.
329318
330 - `BetaManagedAgentsSystemMessageEventParams object { content, type }`
319 format: int32
320
321 - `BetaManagedAgentsSystemMessageEventParams object`
331322
332323 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.
333324
from line 330
339330
340331 The text content.
341332
333 minLength: 1
334
342335 - `type: "text"`
343336
344 - `"text"`
345
346337 - `type: "system.message"`
347338
348 - `"system.message"`
349
350339- `name: string`
351340
352341 Human-readable name for the deployment.
353342
343 minLength: 1, maxLength: 256
344
354345- `budget: optional BetaManagedAgentsBudgetLimit or null`
355346
356347 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 358
367358
368359 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.
369360
370 - `"USD"`
371
372361 - `type: "limit"`
373362
374 - `"limit"`
375
376363- `description: optional string or null`
377364
378365 Description of what the deployment does.
379366
367 maxLength: 2048
368
380369- `metadata: optional map[string]`
381370
382371 Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.
from line 374
385374
386375 Resources (e.g. repositories, files) to mount into each session's container. Maximum 500.
387376
388 - `BetaManagedAgentsGitHubRepositoryResourceParams object { authorization_token, type, url, 2 more }`
377 - `BetaManagedAgentsGitHubRepositoryResourceParams object`
389378
390379 Mount a GitHub repository into the session's container.
391380
from line 382
393382
394383 GitHub authorization token used to clone the repository.
395384
385 minLength: 1, maxLength: 4096
386
396387 - `type: "github_repository"`
397388
398 - `"github_repository"`
399
400389 - `url: string`
401390
402391 Github URL of the repository
403392
393 minLength: 1, maxLength: 2048
394
404395 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
405396
406397 Branch or commit to check out. Defaults to the repository's default branch.
407398
408 - `BetaManagedAgentsBranchCheckout object { name, type }`
399 - `BetaManagedAgentsBranchCheckout object`
409400
410401 - `name: string`
411402
412403 Branch name to check out.
413404
405 minLength: 1, maxLength: 255
406
414407 - `type: "branch"`
415408
416 - `"branch"`
417
418 - `BetaManagedAgentsCommitCheckout object { sha, type }`
409 - `BetaManagedAgentsCommitCheckout object`
419410
420411 - `sha: string`
421412
422413 Full commit SHA to check out.
423414
415 minLength: 7, maxLength: 64
416
424417 - `type: "commit"`
425418
426 - `"commit"`
427
428419 - `mount_path: optional string or null`
429420
430421 Mount path in the container. Defaults to `/workspace/<repo-name>`.
431422
432 - `BetaManagedAgentsFileResourceParams object { file_id, type, mount_path }`
423 minLength: 1, maxLength: 4096
424
425 - `BetaManagedAgentsFileResourceParams object`
433426
434427 Mount a file uploaded via the Files API into the session.
435428
from line 430
437430
438431 ID of a previously uploaded file.
439432
433 minLength: 1, maxLength: 128
434
440435 - `type: "file"`
441436
442 - `"file"`
443
444437 - `mount_path: optional string or null`
445438
446439 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
447440
448 - `BetaManagedAgentsMemoryStoreResourceParam object { memory_store_id, type, access, instructions }`
441 minLength: 1, maxLength: 4096
442
443 - `BetaManagedAgentsMemoryStoreResourceParam object`
449444
450445 Parameters for attaching a memory store to an agent session.
451446
from line 450
455450
456451 - `type: "memory_store"`
457452
458 - `"memory_store"`
459
460453 - `access: optional "read_write" or "read_only" or null`
461454
462455 Access mode for an attached memory store.
from line 462
469462
470463 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
471464
465 maxLength: 4096
466
472467- `schedule: optional BetaManagedAgentsScheduleParams or null`
473468
474469 5-field POSIX cron schedule. Literal wall-clock matching in the configured timezone.
from line 472
477472
478473 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).
479474
475 minLength: 1, maxLength: 256
476
480477 - `timezone: string`
481478
482479 Required. IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). Validated against the IANA timezone database.
483480
481 minLength: 1
482
484483 - `type: "cron"`
485484
486 - `"cron"`
487
488485- `vault_ids: optional array of string`
489486
490487 Vault IDs for stored credentials the agent can use during sessions created from this deployment. Maximum 50.
491488
492489### Returns
493490
494- `BetaManagedAgentsDeployment object { id, agent, archived_at, 14 more }`
491- `BetaManagedAgentsDeployment object`
495492
496493 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.
497494
from line 504
507504
508505 - `type: "agent"`
509506
510 - `"agent"`
511
512507 - `version: number`
513508
509 format: int32
510
514511 - `archived_at: string or null`
515512
516513 A timestamp in RFC 3339 format
517514
515 format: date-time
516
518517 - `created_at: string`
519518
520519 A timestamp in RFC 3339 format
521520
521 format: date-time
522
522523 - `description: string or null`
523524
524525 Description of what the deployment does.
from line 532
531532
532533 Events sent to each session immediately after creation.
533534
534 - `BetaManagedAgentsDeploymentUserMessageEvent object { content, type }`
535 - `BetaManagedAgentsDeploymentUserMessageEvent object`
535536
536537 A user message sent to the session.
537538
from line 540
539540
540541 Array of content blocks for the user message.
541542
542 - `BetaManagedAgentsTextBlock object { text, type }`
543 - `BetaManagedAgentsTextBlock object`
543544
544545 Regular text content.
545546
from line 548
547548
548549 The text content.
549550
551 minLength: 1
552
550553 - `type: "text"`
551554
552 - `"text"`
553
554 - `BetaManagedAgentsImageBlock object { source, type }`
555 - `BetaManagedAgentsImageBlock object`
555556
556557 Image content specified directly as base64 data or as a reference via a URL.
557558
from line 560
559560
560561 Union type for image source variants.
561562
562 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
563 - `BetaManagedAgentsBase64ImageSource object`
563564
564565 Base64-encoded image data.
565566
from line 568
567568
568569 Base64-encoded image data.
569570
571 minLength: 1
572
570573 - `media_type: string`
571574
572575 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
573576
577 minLength: 1
578
574579 - `type: "base64"`
575580
576 - `"base64"`
577
578 - `BetaManagedAgentsURLImageSource object { type, url }`
581 - `BetaManagedAgentsURLImageSource object`
579582
580583 Image referenced by URL.
581584
582585 - `type: "url"`
583586
584 - `"url"`
585
586587 - `url: string`
587588
588589 URL of the image to fetch.
589590
590 - `BetaManagedAgentsFileImageSource object { file_id, type }`
591 minLength: 1
592
593 - `BetaManagedAgentsFileImageSource object`
591594
592595 Image referenced by file ID.
593596
from line 598
595598
596599 ID of a previously uploaded file.
597600
601 minLength: 1
602
598603 - `type: "file"`
599604
600 - `"file"`
601
602605 - `type: "image"`
603606
604 - `"image"`
605
606 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
607 - `BetaManagedAgentsDocumentBlock object`
607608
608609 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
609610
from line 612
611612
612613 Union type for document source variants.
613614
614 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
615 - `BetaManagedAgentsBase64DocumentSource object`
615616
616617 Base64-encoded document data.
617618
from line 620
619620
620621 Base64-encoded document data.
621622
623 minLength: 1
624
622625 - `media_type: string`
623626
624627 MIME type of the document (e.g., "application/pdf").
625628
629 minLength: 1
630
626631 - `type: "base64"`
627632
628 - `"base64"`
629
630 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
633 - `BetaManagedAgentsPlainTextDocumentSource object`
631634
632635 Plain text document content.
633636
from line 638
635638
636639 The plain text content.
637640
641 minLength: 1
642
638643 - `media_type: "text/plain"`
639644
640645 MIME type of the text content. Must be "text/plain".
641646
642 - `"text/plain"`
643
644647 - `type: "text"`
645648
646 - `"text"`
647
648 - `BetaManagedAgentsURLDocumentSource object { type, url }`
649 - `BetaManagedAgentsURLDocumentSource object`
649650
650651 Document referenced by URL.
651652
652653 - `type: "url"`
653654
654 - `"url"`
655
656655 - `url: string`
657656
658657 URL of the document to fetch.
659658
660 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
659 minLength: 1
660
661 - `BetaManagedAgentsFileDocumentSource object`
661662
662663 Document referenced by file ID.
663664
from line 666
665666
666667 ID of a previously uploaded file.
667668
669 minLength: 1
670
668671 - `type: "file"`
669672
670 - `"file"`
671
672673 - `type: "document"`
673674
674 - `"document"`
675
676675 - `context: optional string or null`
677676
678677 Additional context about the document for the model.
from line 680
681680
682681 The title of the document.
683682
684 - `BetaManagedAgentsRedactedBlock object { type }`
683 - `BetaManagedAgentsRedactedBlock object`
685684
686685 Placeholder for content withheld by Anthropic model policy.
687686
688687 - `type: "redacted"`
689688
690 - `"redacted"`
691
692689 - `type: "user.message"`
693690
694 - `"user.message"`
695
696 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object { description, rubric, type, max_iterations }`
691 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`
697692
698693 An outcome the agent should work toward. The agent begins work on receipt.
699694
from line 700
705700
706701 Rubric for grading the quality of an outcome.
707702
708 - `BetaManagedAgentsFileRubric object { file_id, type }`
703 - `BetaManagedAgentsFileRubric object`
709704
710705 Rubric referenced by a file uploaded via the Files API.
711706
from line 710
715710
716711 - `type: "file"`
717712
718 - `"file"`
719
720 - `BetaManagedAgentsTextRubric object { content, type }`
713 - `BetaManagedAgentsTextRubric object`
721714
722715 Rubric content provided inline as text.
723716
from line 720
727720
728721 - `type: "text"`
729722
730 - `"text"`
731
732723 - `type: "user.define_outcome"`
733724
734 - `"user.define_outcome"`
735
736725 - `max_iterations: optional number or null`
737726
738727 Eval→revision cycles before giving up. Default 3, max 20.
739728
740 - `BetaManagedAgentsDeploymentSystemMessageEvent object { content, type }`
729 format: int32
730
731 - `BetaManagedAgentsDeploymentSystemMessageEvent object`
741732
742733 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.
743734
from line 740
749740
750741 The text content.
751742
743 minLength: 1
744
752745 - `type: "text"`
753746
754 - `"text"`
755
756747 - `type: "system.message"`
757748
758 - `"system.message"`
759
760749 - `metadata: map[string]`
761750
762751 Arbitrary key-value metadata. Maximum 16 pairs.
from line 758
769758
770759 Why a deployment is paused. Non-null exactly when `status` is `paused`.
771760
772 - `BetaManagedAgentsManualDeploymentPausedReason object { type }`
761 - `BetaManagedAgentsManualDeploymentPausedReason object`
773762
774763 The caller invoked the pause endpoint on the deployment.
775764
776765 - `type: "manual"`
777766
778 - `"manual"`
779
780 - `BetaManagedAgentsErrorDeploymentPausedReason object { error, type }`
767 - `BetaManagedAgentsErrorDeploymentPausedReason object`
781768
782769 A scheduled fire recorded a failed run whose error auto-pauses the deployment.
783770
from line 772
785772
786773 The error that triggered an auto-pause. Matches the failed run's `error.type`.
787774
788 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object { type }`
775 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object`
789776
790777 The deployment's environment was archived.
791778
792779 - `type: "environment_archived_error"`
793780
794 - `"environment_archived_error"`
795
796 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object { type }`
781 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object`
797782
798783 The deployment's agent was archived.
799784
800785 - `type: "agent_archived_error"`
801786
802 - `"agent_archived_error"`
803
804 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object { type }`
787 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object`
805788
806789 The deployment's environment no longer exists.
807790
808791 - `type: "environment_not_found_error"`
809792
810 - `"environment_not_found_error"`
811
812 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object { type }`
793 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object`
813794
814795 A vault referenced by the deployment no longer exists.
815796
816797 - `type: "vault_not_found_error"`
817798
818 - `"vault_not_found_error"`
819
820 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object { type }`
799 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object`
821800
822801 A file resource referenced by the deployment no longer exists.
823802
824803 - `type: "file_not_found_error"`
825804
826 - `"file_not_found_error"`
827
828 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object { type }`
805 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object`
829806
830807 A referenced resource no longer exists and its kind was not reported.
831808
832809 - `type: "session_resource_not_found_error"`
833810
834 - `"session_resource_not_found_error"`
835
836 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object { type }`
811 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object`
837812
838813 The deployment's workspace was archived.
839814
840815 - `type: "workspace_archived_error"`
841816
842 - `"workspace_archived_error"`
843
844 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object { type }`
817 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object`
845818
846819 The deployment's organization is disabled.
847820
848821 - `type: "organization_disabled_error"`
849822
850 - `"organization_disabled_error"`
851
852 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object { type }`
823 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object`
853824
854825 A memory store referenced by the deployment is archived.
855826
856827 - `type: "memory_store_archived_error"`
857828
858 - `"memory_store_archived_error"`
859
860 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object { type }`
829 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object`
861830
862831 A skill referenced by the deployment's agent no longer exists.
863832
864833 - `type: "skill_not_found_error"`
865834
866 - `"skill_not_found_error"`
867
868 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object { type }`
835 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object`
869836
870837 A vault referenced by the deployment is archived.
871838
872839 - `type: "vault_archived_error"`
873840
874 - `"vault_archived_error"`
875
876 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object { type }`
841 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object`
877842
878843 An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.
879844
880845 - `type: "unknown_error"`
881846
882 - `"unknown_error"`
883
884 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object { type }`
847 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object`
885848
886849 The deployment configures resources, but its environment is self-hosted and cannot mount them.
887850
888851 - `type: "self_hosted_resources_unsupported_error"`
889852
890 - `"self_hosted_resources_unsupported_error"`
891
892 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object { type }`
853 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object`
893854
894855 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
895856
896857 - `type: "mcp_egress_blocked_error"`
897858
898 - `"mcp_egress_blocked_error"`
899
900859 - `type: "error"`
901860
902 - `"error"`
903
904861 - `resources: array of BetaManagedAgentsSessionResourceConfig`
905862
906863 Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.
907864
908 - `BetaManagedAgentsGitHubRepositoryResourceConfig object { type, url, checkout, mount_path }`
865 - `BetaManagedAgentsGitHubRepositoryResourceConfig object`
909866
910867 A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.
911868
912869 - `type: "github_repository"`
913870
914 - `"github_repository"`
915
916871 - `url: string`
917872
918873 Github URL of the repository
from line 876
921876
922877 Branch or commit to check out. Defaults to the repository's default branch.
923878
924 - `BetaManagedAgentsBranchCheckout object { name, type }`
879 - `BetaManagedAgentsBranchCheckout object`
925880
926881 - `name: string`
927882
928883 Branch name to check out.
929884
885 minLength: 1, maxLength: 255
886
930887 - `type: "branch"`
931888
932 - `"branch"`
933
934 - `BetaManagedAgentsCommitCheckout object { sha, type }`
889 - `BetaManagedAgentsCommitCheckout object`
935890
936891 - `sha: string`
937892
938893 Full commit SHA to check out.
939894
895 minLength: 7, maxLength: 64
896
940897 - `type: "commit"`
941898
942 - `"commit"`
943
944899 - `mount_path: optional string or null`
945900
946901 Mount path in the container. Defaults to `/workspace/<repo-name>`.
947902
948 - `BetaManagedAgentsFileResourceConfig object { file_id, type, mount_path }`
903 - `BetaManagedAgentsFileResourceConfig object`
949904
950905 A file mounted into each session's container.
951906
from line 910
955910
956911 - `type: "file"`
957912
958 - `"file"`
959
960913 - `mount_path: optional string or null`
961914
962915 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
963916
964 - `BetaManagedAgentsMemoryStoreResourceConfig object { memory_store_id, type, access, instructions }`
917 - `BetaManagedAgentsMemoryStoreResourceConfig object`
965918
966919 A memory store attached to each session created from this deployment.
967920
from line 924
971924
972925 - `type: "memory_store"`
973926
974 - `"memory_store"`
975
976927 - `access: optional "read_write" or "read_only" or null`
977928
978929 Access mode for an attached memory store.
from line 944
993944
994945 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).
995946
947 minLength: 1, maxLength: 256
948
996949 - `timezone: string`
997950
998951 IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").
999952
953 minLength: 1
954
1000955 - `type: "cron"`
1001956
1002 - `"cron"`
1003
1004957 - `last_run_at: optional string or null`
1005958
1006959 A timestamp in RFC 3339 format
1007960
961 format: date-time
962
1008963 - `upcoming_runs_at: optional array of string`
1009964
1010965 Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.
from line 974
1019974
1020975 - `type: "deployment"`
1021976
1022 - `"deployment"`
1023
1024977 - `updated_at: string`
1025978
1026979 A timestamp in RFC 3339 format
1027980
981 format: date-time
982
1028983 - `vault_ids: array of string`
1029984
1030985 Vault IDs supplying stored credentials for sessions created from this deployment.
from line 1000
10451000
10461001 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.
10471002
1048 - `"USD"`
1049
10501003 - `type: "limit"`
10511004
1052 - `"limit"`
1053
10541005### Example
10551006
1056```http
1007```bash
10571008curl https://api.anthropic.com/v1/deployments \
10581009 -H 'Content-Type: application/json' \
10591010 -H 'anthropic-version: 2023-06-01' \
from line 1028
10771028 }'
10781029```
10791030
1080#### Response
1031#### Response (200)
10811032
10821033```json
10831034{
from line 1097
11461097
11471098## List Deployments
11481099
1149**get** `/v1/deployments`
1100**GET** `/v1/deployments`
11501101
11511102List Deployments
11521103
1153### Query Parameters
1104### Query parameters
11541105
11551106- `agent_id: optional string`
11561107
from line 1111
11601111
11611112 Return deployments created at or after this time (inclusive).
11621113
1114 format: date-time
1115
11631116- `"created_at[lte]": optional string`
11641117
11651118 Return deployments created at or before this time (inclusive).
11661119
1120 format: date-time
1121
11671122- `include_archived: optional boolean`
11681123
11691124 When true, includes archived deployments. Default: false (exclude archived).
from line 1127
11721127
11731128 Maximum results per page. Default 20, maximum 100.
11741129
1130 format: int32
1131
11751132- `page: optional string`
11761133
11771134 Opaque pagination cursor.
from line 1141
11841141
11851142 - `"paused"`
11861143
1187### Header Parameters
1144### Headers
11881145
11891146- `"anthropic-beta": optional array of AnthropicBeta`
11901147
from line 1237
12801237
12811238 - `type: "agent"`
12821239
1283 - `"agent"`
1284
12851240 - `version: number`
12861241
1242 format: int32
1243
12871244 - `archived_at: string or null`
12881245
12891246 A timestamp in RFC 3339 format
12901247
1248 format: date-time
1249
12911250 - `created_at: string`
12921251
12931252 A timestamp in RFC 3339 format
12941253
1254 format: date-time
1255
12951256 - `description: string or null`
12961257
12971258 Description of what the deployment does.
from line 1265
13041265
13051266 Events sent to each session immediately after creation.
13061267
1307 - `BetaManagedAgentsDeploymentUserMessageEvent object { content, type }`
1268 - `BetaManagedAgentsDeploymentUserMessageEvent object`
13081269
13091270 A user message sent to the session.
13101271
from line 1273
13121273
13131274 Array of content blocks for the user message.
13141275
1315 - `BetaManagedAgentsTextBlock object { text, type }`
1276 - `BetaManagedAgentsTextBlock object`
13161277
13171278 Regular text content.
13181279
from line 1281
13201281
13211282 The text content.
13221283
1284 minLength: 1
1285
13231286 - `type: "text"`
13241287
1325 - `"text"`
1326
1327 - `BetaManagedAgentsImageBlock object { source, type }`
1288 - `BetaManagedAgentsImageBlock object`
13281289
13291290 Image content specified directly as base64 data or as a reference via a URL.
13301291
from line 1293
13321293
13331294 Union type for image source variants.
13341295
1335 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
1296 - `BetaManagedAgentsBase64ImageSource object`
13361297
13371298 Base64-encoded image data.
13381299
from line 1301
13401301
13411302 Base64-encoded image data.
13421303
1304 minLength: 1
1305
13431306 - `media_type: string`
13441307
13451308 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
13461309
1310 minLength: 1
1311
13471312 - `type: "base64"`
13481313
1349 - `"base64"`
1350
1351 - `BetaManagedAgentsURLImageSource object { type, url }`
1314 - `BetaManagedAgentsURLImageSource object`
13521315
13531316 Image referenced by URL.
13541317
13551318 - `type: "url"`
13561319
1357 - `"url"`
1358
13591320 - `url: string`
13601321
13611322 URL of the image to fetch.
13621323
1363 - `BetaManagedAgentsFileImageSource object { file_id, type }`
1324 minLength: 1
1325
1326 - `BetaManagedAgentsFileImageSource object`
13641327
13651328 Image referenced by file ID.
13661329
from line 1331
13681331
13691332 ID of a previously uploaded file.
13701333
1334 minLength: 1
1335
13711336 - `type: "file"`
13721337
1373 - `"file"`
1374
13751338 - `type: "image"`
13761339
1377 - `"image"`
1378
1379 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
1340 - `BetaManagedAgentsDocumentBlock object`
13801341
13811342 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
13821343
from line 1345
13841345
13851346 Union type for document source variants.
13861347
1387 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
1348 - `BetaManagedAgentsBase64DocumentSource object`
13881349
13891350 Base64-encoded document data.
13901351
from line 1353
13921353
13931354 Base64-encoded document data.
13941355
1356 minLength: 1
1357
13951358 - `media_type: string`
13961359
13971360 MIME type of the document (e.g., "application/pdf").
13981361
1362 minLength: 1
1363
13991364 - `type: "base64"`
14001365
1401 - `"base64"`
1402
1403 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
1366 - `BetaManagedAgentsPlainTextDocumentSource object`
14041367
14051368 Plain text document content.
14061369
from line 1371
14081371
14091372 The plain text content.
14101373
1374 minLength: 1
1375
14111376 - `media_type: "text/plain"`
14121377
14131378 MIME type of the text content. Must be "text/plain".
14141379
1415 - `"text/plain"`
1416
14171380 - `type: "text"`
14181381
1419 - `"text"`
1420
1421 - `BetaManagedAgentsURLDocumentSource object { type, url }`
1382 - `BetaManagedAgentsURLDocumentSource object`
14221383
14231384 Document referenced by URL.
14241385
14251386 - `type: "url"`
14261387
1427 - `"url"`
1428
14291388 - `url: string`
14301389
14311390 URL of the document to fetch.
14321391
1433 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
1392 minLength: 1
1393
1394 - `BetaManagedAgentsFileDocumentSource object`
14341395
14351396 Document referenced by file ID.
14361397
from line 1399
14381399
14391400 ID of a previously uploaded file.
14401401
1402 minLength: 1
1403
14411404 - `type: "file"`
14421405
1443 - `"file"`
1444
14451406 - `type: "document"`
14461407
1447 - `"document"`
1448
14491408 - `context: optional string or null`
14501409
14511410 Additional context about the document for the model.
from line 1413
14541413
14551414 The title of the document.
14561415
1457 - `BetaManagedAgentsRedactedBlock object { type }`
1416 - `BetaManagedAgentsRedactedBlock object`
14581417
14591418 Placeholder for content withheld by Anthropic model policy.
14601419
14611420 - `type: "redacted"`
14621421
1463 - `"redacted"`
1464
14651422 - `type: "user.message"`
14661423
1467 - `"user.message"`
1468
1469 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object { description, rubric, type, max_iterations }`
1424 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`
14701425
14711426 An outcome the agent should work toward. The agent begins work on receipt.
14721427
from line 1433
14781433
14791434 Rubric for grading the quality of an outcome.
14801435
1481 - `BetaManagedAgentsFileRubric object { file_id, type }`
1436 - `BetaManagedAgentsFileRubric object`
14821437
14831438 Rubric referenced by a file uploaded via the Files API.
14841439
from line 1443
14881443
14891444 - `type: "file"`
14901445
1491 - `"file"`
1492
1493 - `BetaManagedAgentsTextRubric object { content, type }`
1446 - `BetaManagedAgentsTextRubric object`
14941447
14951448 Rubric content provided inline as text.
14961449
from line 1453
15001453
15011454 - `type: "text"`
15021455
1503 - `"text"`
1504
15051456 - `type: "user.define_outcome"`
15061457
1507 - `"user.define_outcome"`
1508
15091458 - `max_iterations: optional number or null`
15101459
15111460 Eval→revision cycles before giving up. Default 3, max 20.
15121461
1513 - `BetaManagedAgentsDeploymentSystemMessageEvent object { content, type }`
1462 format: int32
1463
1464 - `BetaManagedAgentsDeploymentSystemMessageEvent object`
15141465
15151466 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.
15161467
from line 1473
15221473
15231474 The text content.
15241475
1476 minLength: 1
1477
15251478 - `type: "text"`
15261479
1527 - `"text"`
1528
15291480 - `type: "system.message"`
15301481
1531 - `"system.message"`
1532
15331482 - `metadata: map[string]`
15341483
15351484 Arbitrary key-value metadata. Maximum 16 pairs.
from line 1491
15421491
15431492 Why a deployment is paused. Non-null exactly when `status` is `paused`.
15441493
1545 - `BetaManagedAgentsManualDeploymentPausedReason object { type }`
1494 - `BetaManagedAgentsManualDeploymentPausedReason object`
15461495
15471496 The caller invoked the pause endpoint on the deployment.
15481497
15491498 - `type: "manual"`
15501499
1551 - `"manual"`
1552
1553 - `BetaManagedAgentsErrorDeploymentPausedReason object { error, type }`
1500 - `BetaManagedAgentsErrorDeploymentPausedReason object`
15541501
15551502 A scheduled fire recorded a failed run whose error auto-pauses the deployment.
15561503
from line 1505
15581505
15591506 The error that triggered an auto-pause. Matches the failed run's `error.type`.
15601507
1561 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object { type }`
1508 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object`
15621509
15631510 The deployment's environment was archived.
15641511
15651512 - `type: "environment_archived_error"`
15661513
1567 - `"environment_archived_error"`
1568
1569 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object { type }`
1514 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object`
15701515
15711516 The deployment's agent was archived.
15721517
15731518 - `type: "agent_archived_error"`
15741519
1575 - `"agent_archived_error"`
1576
1577 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object { type }`
1520 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object`
15781521
15791522 The deployment's environment no longer exists.
15801523
15811524 - `type: "environment_not_found_error"`
15821525
1583 - `"environment_not_found_error"`
1584
1585 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object { type }`
1526 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object`
15861527
15871528 A vault referenced by the deployment no longer exists.
15881529
15891530 - `type: "vault_not_found_error"`
15901531
1591 - `"vault_not_found_error"`
1592
1593 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object { type }`
1532 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object`
15941533
15951534 A file resource referenced by the deployment no longer exists.
15961535
15971536 - `type: "file_not_found_error"`
15981537
1599 - `"file_not_found_error"`
1600
1601 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object { type }`
1538 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object`
16021539
16031540 A referenced resource no longer exists and its kind was not reported.
16041541
16051542 - `type: "session_resource_not_found_error"`
16061543
1607 - `"session_resource_not_found_error"`
1608
1609 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object { type }`
1544 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object`
16101545
16111546 The deployment's workspace was archived.
16121547
16131548 - `type: "workspace_archived_error"`
16141549
1615 - `"workspace_archived_error"`
1616
1617 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object { type }`
1550 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object`
16181551
16191552 The deployment's organization is disabled.
16201553
16211554 - `type: "organization_disabled_error"`
16221555
1623 - `"organization_disabled_error"`
1624
1625 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object { type }`
1556 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object`
16261557
16271558 A memory store referenced by the deployment is archived.
16281559
16291560 - `type: "memory_store_archived_error"`
16301561
1631 - `"memory_store_archived_error"`
1632
1633 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object { type }`
1562 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object`
16341563
16351564 A skill referenced by the deployment's agent no longer exists.
16361565
16371566 - `type: "skill_not_found_error"`
16381567
1639 - `"skill_not_found_error"`
1640
1641 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object { type }`
1568 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object`
16421569
16431570 A vault referenced by the deployment is archived.
16441571
16451572 - `type: "vault_archived_error"`
16461573
1647 - `"vault_archived_error"`
1648
1649 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object { type }`
1574 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object`
16501575
16511576 An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.
16521577
16531578 - `type: "unknown_error"`
16541579
1655 - `"unknown_error"`
1656
1657 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object { type }`
1580 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object`
16581581
16591582 The deployment configures resources, but its environment is self-hosted and cannot mount them.
16601583
16611584 - `type: "self_hosted_resources_unsupported_error"`
16621585
1663 - `"self_hosted_resources_unsupported_error"`
1664
1665 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object { type }`
1586 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object`
16661587
16671588 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
16681589
16691590 - `type: "mcp_egress_blocked_error"`
16701591
1671 - `"mcp_egress_blocked_error"`
1672
16731592 - `type: "error"`
16741593
1675 - `"error"`
1676
16771594 - `resources: array of BetaManagedAgentsSessionResourceConfig`
16781595
16791596 Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.
16801597
1681 - `BetaManagedAgentsGitHubRepositoryResourceConfig object { type, url, checkout, mount_path }`
1598 - `BetaManagedAgentsGitHubRepositoryResourceConfig object`
16821599
16831600 A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.
16841601
16851602 - `type: "github_repository"`
16861603
1687 - `"github_repository"`
1688
16891604 - `url: string`
16901605
16911606 Github URL of the repository
from line 1609
16941609
16951610 Branch or commit to check out. Defaults to the repository's default branch.
16961611
1697 - `BetaManagedAgentsBranchCheckout object { name, type }`
1612 - `BetaManagedAgentsBranchCheckout object`
16981613
16991614 - `name: string`
17001615
17011616 Branch name to check out.
17021617
1618 minLength: 1, maxLength: 255
1619
17031620 - `type: "branch"`
17041621
1705 - `"branch"`
1706
1707 - `BetaManagedAgentsCommitCheckout object { sha, type }`
1622 - `BetaManagedAgentsCommitCheckout object`
17081623
17091624 - `sha: string`
17101625
17111626 Full commit SHA to check out.
17121627
1628 minLength: 7, maxLength: 64
1629
17131630 - `type: "commit"`
17141631
1715 - `"commit"`
1716
17171632 - `mount_path: optional string or null`
17181633
17191634 Mount path in the container. Defaults to `/workspace/<repo-name>`.
17201635
1721 - `BetaManagedAgentsFileResourceConfig object { file_id, type, mount_path }`
1636 - `BetaManagedAgentsFileResourceConfig object`
17221637
17231638 A file mounted into each session's container.
17241639
from line 1643
17281643
17291644 - `type: "file"`
17301645
1731 - `"file"`
1732
17331646 - `mount_path: optional string or null`
17341647
17351648 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
17361649
1737 - `BetaManagedAgentsMemoryStoreResourceConfig object { memory_store_id, type, access, instructions }`
1650 - `BetaManagedAgentsMemoryStoreResourceConfig object`
17381651
17391652 A memory store attached to each session created from this deployment.
17401653
from line 1657
17441657
17451658 - `type: "memory_store"`
17461659
1747 - `"memory_store"`
1748
17491660 - `access: optional "read_write" or "read_only" or null`
17501661
17511662 Access mode for an attached memory store.
from line 1677
17661677
17671678 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).
17681679
1680 minLength: 1, maxLength: 256
1681
17691682 - `timezone: string`
17701683
17711684 IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").
17721685
1686 minLength: 1
1687
17731688 - `type: "cron"`
17741689
1775 - `"cron"`
1776
17771690 - `last_run_at: optional string or null`
17781691
17791692 A timestamp in RFC 3339 format
17801693
1694 format: date-time
1695
17811696 - `upcoming_runs_at: optional array of string`
17821697
17831698 Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.
from line 1707
17921707
17931708 - `type: "deployment"`
17941709
1795 - `"deployment"`
1796
17971710 - `updated_at: string`
17981711
17991712 A timestamp in RFC 3339 format
18001713
1714 format: date-time
1715
18011716 - `vault_ids: array of string`
18021717
18031718 Vault IDs supplying stored credentials for sessions created from this deployment.
from line 1733
18181733
18191734 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.
18201735
1821 - `"USD"`
1822
18231736 - `type: "limit"`
18241737
1825 - `"limit"`
1826
18271738- `next_page: optional string or null`
18281739
18291740 Opaque cursor for the next page. Null when no more results.
18301741
18311742### Example
18321743
1833```http
1744```bash
18341745curl https://api.anthropic.com/v1/deployments \
18351746 -H 'anthropic-version: 2023-06-01' \
18361747 -H 'anthropic-beta: managed-agents-2026-04-01' \
18371748 -H "X-Api-Key: $ANTHROPIC_API_KEY"
18381749```
18391750
1840#### Response
1751#### Response (200)
18411752
18421753```json
18431754{
from line 1822
19111822
19121823## Get Deployment
19131824
1914**get** `/v1/deployments/{deployment_id}`
1825**GET** `/v1/deployments/{deployment_id}`
19151826
19161827Get Deployment
19171828
1918### Path Parameters
1829### Path parameters
19191830
19201831- `deployment_id: string`
19211832
1922### Header Parameters
1833### Headers
19231834
19241835- `"anthropic-beta": optional array of AnthropicBeta`
19251836
from line 1910
19991910
20001911### Returns
20011912
2002- `BetaManagedAgentsDeployment object { id, agent, archived_at, 14 more }`
1913- `BetaManagedAgentsDeployment object`
20031914
20041915 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.
20051916
from line 1926
20151926
20161927 - `type: "agent"`
20171928
2018 - `"agent"`
2019
20201929 - `version: number`
20211930
1931 format: int32
1932
20221933 - `archived_at: string or null`
20231934
20241935 A timestamp in RFC 3339 format
20251936
1937 format: date-time
1938
20261939 - `created_at: string`
20271940
20281941 A timestamp in RFC 3339 format
20291942
1943 format: date-time
1944
20301945 - `description: string or null`
20311946
20321947 Description of what the deployment does.
from line 1954
20391954
20401955 Events sent to each session immediately after creation.
20411956
2042 - `BetaManagedAgentsDeploymentUserMessageEvent object { content, type }`
1957 - `BetaManagedAgentsDeploymentUserMessageEvent object`
20431958
20441959 A user message sent to the session.
20451960
from line 1962
20471962
20481963 Array of content blocks for the user message.
20491964
2050 - `BetaManagedAgentsTextBlock object { text, type }`
1965 - `BetaManagedAgentsTextBlock object`
20511966
20521967 Regular text content.
20531968
from line 1970
20551970
20561971 The text content.
20571972
1973 minLength: 1
1974
20581975 - `type: "text"`
20591976
2060 - `"text"`
2061
2062 - `BetaManagedAgentsImageBlock object { source, type }`
1977 - `BetaManagedAgentsImageBlock object`
20631978
20641979 Image content specified directly as base64 data or as a reference via a URL.
20651980
from line 1982
20671982
20681983 Union type for image source variants.
20691984
2070 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
1985 - `BetaManagedAgentsBase64ImageSource object`
20711986
20721987 Base64-encoded image data.
20731988
from line 1990
20751990
20761991 Base64-encoded image data.
20771992
1993 minLength: 1
1994
20781995 - `media_type: string`
20791996
20801997 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
20811998
1999 minLength: 1
2000
20822001 - `type: "base64"`
20832002
2084 - `"base64"`
2085
2086 - `BetaManagedAgentsURLImageSource object { type, url }`
2003 - `BetaManagedAgentsURLImageSource object`
20872004
20882005 Image referenced by URL.
20892006
20902007 - `type: "url"`
20912008
2092 - `"url"`
2093
20942009 - `url: string`
20952010
20962011 URL of the image to fetch.
20972012
2098 - `BetaManagedAgentsFileImageSource object { file_id, type }`
2013 minLength: 1
2014
2015 - `BetaManagedAgentsFileImageSource object`
20992016
21002017 Image referenced by file ID.
21012018
from line 2020
21032020
21042021 ID of a previously uploaded file.
21052022
2023 minLength: 1
2024
21062025 - `type: "file"`
21072026
2108 - `"file"`
2109
21102027 - `type: "image"`
21112028
2112 - `"image"`
2113
2114 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
2029 - `BetaManagedAgentsDocumentBlock object`
21152030
21162031 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
21172032
from line 2034
21192034
21202035 Union type for document source variants.
21212036
2122 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
2037 - `BetaManagedAgentsBase64DocumentSource object`
21232038
21242039 Base64-encoded document data.
21252040
from line 2042
21272042
21282043 Base64-encoded document data.
21292044
2045 minLength: 1
2046
21302047 - `media_type: string`
21312048
21322049 MIME type of the document (e.g., "application/pdf").
21332050
2051 minLength: 1
2052
21342053 - `type: "base64"`
21352054
2136 - `"base64"`
2137
2138 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
2055 - `BetaManagedAgentsPlainTextDocumentSource object`
21392056
21402057 Plain text document content.
21412058
from line 2060
21432060
21442061 The plain text content.
21452062
2063 minLength: 1
2064
21462065 - `media_type: "text/plain"`
21472066
21482067 MIME type of the text content. Must be "text/plain".
21492068
2150 - `"text/plain"`
2151
21522069 - `type: "text"`
21532070
2154 - `"text"`
2155
2156 - `BetaManagedAgentsURLDocumentSource object { type, url }`
2071 - `BetaManagedAgentsURLDocumentSource object`
21572072
21582073 Document referenced by URL.
21592074
21602075 - `type: "url"`
21612076
2162 - `"url"`
2163
21642077 - `url: string`
21652078
21662079 URL of the document to fetch.
21672080
2168 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
2081 minLength: 1
2082
2083 - `BetaManagedAgentsFileDocumentSource object`
21692084
21702085 Document referenced by file ID.
21712086
from line 2088
21732088
21742089 ID of a previously uploaded file.
21752090
2091 minLength: 1
2092
21762093 - `type: "file"`
21772094
2178 - `"file"`
2179
21802095 - `type: "document"`
21812096
2182 - `"document"`
2183
21842097 - `context: optional string or null`
21852098
21862099 Additional context about the document for the model.
from line 2102
21892102
21902103 The title of the document.
21912104
2192 - `BetaManagedAgentsRedactedBlock object { type }`
2105 - `BetaManagedAgentsRedactedBlock object`
21932106
21942107 Placeholder for content withheld by Anthropic model policy.
21952108
21962109 - `type: "redacted"`
21972110
2198 - `"redacted"`
2199
22002111 - `type: "user.message"`
22012112
2202 - `"user.message"`
2203
2204 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object { description, rubric, type, max_iterations }`
2113 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`
22052114
22062115 An outcome the agent should work toward. The agent begins work on receipt.
22072116
from line 2122
22132122
22142123 Rubric for grading the quality of an outcome.
22152124
2216 - `BetaManagedAgentsFileRubric object { file_id, type }`
2125 - `BetaManagedAgentsFileRubric object`
22172126
22182127 Rubric referenced by a file uploaded via the Files API.
22192128
from line 2132
22232132
22242133 - `type: "file"`
22252134
2226 - `"file"`
2227
2228 - `BetaManagedAgentsTextRubric object { content, type }`
2135 - `BetaManagedAgentsTextRubric object`
22292136
22302137 Rubric content provided inline as text.
22312138
from line 2142
22352142
22362143 - `type: "text"`
22372144
2238 - `"text"`
2239
22402145 - `type: "user.define_outcome"`
22412146
2242 - `"user.define_outcome"`
2243
22442147 - `max_iterations: optional number or null`
22452148
22462149 Eval→revision cycles before giving up. Default 3, max 20.
22472150
2248 - `BetaManagedAgentsDeploymentSystemMessageEvent object { content, type }`
2151 format: int32
2152
2153 - `BetaManagedAgentsDeploymentSystemMessageEvent object`
22492154
22502155 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.
22512156
from line 2162
22572162
22582163 The text content.
22592164
2165 minLength: 1
2166
22602167 - `type: "text"`
22612168
2262 - `"text"`
2263
22642169 - `type: "system.message"`
22652170
2266 - `"system.message"`
2267
22682171 - `metadata: map[string]`
22692172
22702173 Arbitrary key-value metadata. Maximum 16 pairs.
from line 2180
22772180
22782181 Why a deployment is paused. Non-null exactly when `status` is `paused`.
22792182
2280 - `BetaManagedAgentsManualDeploymentPausedReason object { type }`
2183 - `BetaManagedAgentsManualDeploymentPausedReason object`
22812184
22822185 The caller invoked the pause endpoint on the deployment.
22832186
22842187 - `type: "manual"`
22852188
2286 - `"manual"`
2287
2288 - `BetaManagedAgentsErrorDeploymentPausedReason object { error, type }`
2189 - `BetaManagedAgentsErrorDeploymentPausedReason object`
22892190
22902191 A scheduled fire recorded a failed run whose error auto-pauses the deployment.
22912192
from line 2194
22932194
22942195 The error that triggered an auto-pause. Matches the failed run's `error.type`.
22952196
2296 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object { type }`
2197 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object`
22972198
22982199 The deployment's environment was archived.
22992200
23002201 - `type: "environment_archived_error"`
23012202
2302 - `"environment_archived_error"`
2303
2304 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object { type }`
2203 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object`
23052204
23062205 The deployment's agent was archived.
23072206
23082207 - `type: "agent_archived_error"`
23092208
2310 - `"agent_archived_error"`
2311
2312 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object { type }`
2209 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object`
23132210
23142211 The deployment's environment no longer exists.
23152212
23162213 - `type: "environment_not_found_error"`
23172214
2318 - `"environment_not_found_error"`
2319
2320 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object { type }`
2215 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object`
23212216
23222217 A vault referenced by the deployment no longer exists.
23232218
23242219 - `type: "vault_not_found_error"`
23252220
2326 - `"vault_not_found_error"`
2327
2328 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object { type }`
2221 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object`
23292222
23302223 A file resource referenced by the deployment no longer exists.
23312224
23322225 - `type: "file_not_found_error"`
23332226
2334 - `"file_not_found_error"`
2335
2336 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object { type }`
2227 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object`
23372228
23382229 A referenced resource no longer exists and its kind was not reported.
23392230
23402231 - `type: "session_resource_not_found_error"`
23412232
2342 - `"session_resource_not_found_error"`
2343
2344 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object { type }`
2233 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object`
23452234
23462235 The deployment's workspace was archived.
23472236
23482237 - `type: "workspace_archived_error"`
23492238
2350 - `"workspace_archived_error"`
2351
2352 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object { type }`
2239 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object`
23532240
23542241 The deployment's organization is disabled.
23552242
23562243 - `type: "organization_disabled_error"`
23572244
2358 - `"organization_disabled_error"`
2359
2360 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object { type }`
2245 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object`
23612246
23622247 A memory store referenced by the deployment is archived.
23632248
23642249 - `type: "memory_store_archived_error"`
23652250
2366 - `"memory_store_archived_error"`
2367
2368 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object { type }`
2251 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object`
23692252
23702253 A skill referenced by the deployment's agent no longer exists.
23712254
23722255 - `type: "skill_not_found_error"`
23732256
2374 - `"skill_not_found_error"`
2375
2376 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object { type }`
2257 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object`
23772258
23782259 A vault referenced by the deployment is archived.
23792260
23802261 - `type: "vault_archived_error"`
23812262
2382 - `"vault_archived_error"`
2383
2384 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object { type }`
2263 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object`
23852264
23862265 An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.
23872266
23882267 - `type: "unknown_error"`
23892268
2390 - `"unknown_error"`
2391
2392 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object { type }`
2269 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object`
23932270
23942271 The deployment configures resources, but its environment is self-hosted and cannot mount them.
23952272
23962273 - `type: "self_hosted_resources_unsupported_error"`
23972274
2398 - `"self_hosted_resources_unsupported_error"`
2399
2400 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object { type }`
2275 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object`
24012276
24022277 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
24032278
24042279 - `type: "mcp_egress_blocked_error"`
24052280
2406 - `"mcp_egress_blocked_error"`
2407
24082281 - `type: "error"`
24092282
2410 - `"error"`
2411
24122283 - `resources: array of BetaManagedAgentsSessionResourceConfig`
24132284
24142285 Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.
24152286
2416 - `BetaManagedAgentsGitHubRepositoryResourceConfig object { type, url, checkout, mount_path }`
2287 - `BetaManagedAgentsGitHubRepositoryResourceConfig object`
24172288
24182289 A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.
24192290
24202291 - `type: "github_repository"`
24212292
2422 - `"github_repository"`
2423
24242293 - `url: string`
24252294
24262295 Github URL of the repository
from line 2298
24292298
24302299 Branch or commit to check out. Defaults to the repository's default branch.
24312300
2432 - `BetaManagedAgentsBranchCheckout object { name, type }`
2301 - `BetaManagedAgentsBranchCheckout object`
24332302
24342303 - `name: string`
24352304
24362305 Branch name to check out.
24372306
2307 minLength: 1, maxLength: 255
2308
24382309 - `type: "branch"`
24392310
2440 - `"branch"`
2441
2442 - `BetaManagedAgentsCommitCheckout object { sha, type }`
2311 - `BetaManagedAgentsCommitCheckout object`
24432312
24442313 - `sha: string`
24452314
24462315 Full commit SHA to check out.
24472316
2317 minLength: 7, maxLength: 64
2318
24482319 - `type: "commit"`
24492320
2450 - `"commit"`
2451
24522321 - `mount_path: optional string or null`
24532322
24542323 Mount path in the container. Defaults to `/workspace/<repo-name>`.
24552324
2456 - `BetaManagedAgentsFileResourceConfig object { file_id, type, mount_path }`
2325 - `BetaManagedAgentsFileResourceConfig object`
24572326
24582327 A file mounted into each session's container.
24592328
from line 2332
24632332
24642333 - `type: "file"`
24652334
2466 - `"file"`
2467
24682335 - `mount_path: optional string or null`
24692336
24702337 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
24712338
2472 - `BetaManagedAgentsMemoryStoreResourceConfig object { memory_store_id, type, access, instructions }`
2339 - `BetaManagedAgentsMemoryStoreResourceConfig object`
24732340
24742341 A memory store attached to each session created from this deployment.
24752342
from line 2346
24792346
24802347 - `type: "memory_store"`
24812348
2482 - `"memory_store"`
2483
24842349 - `access: optional "read_write" or "read_only" or null`
24852350
24862351 Access mode for an attached memory store.
from line 2366
25012366
25022367 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).
25032368
2369 minLength: 1, maxLength: 256
2370
25042371 - `timezone: string`
25052372
25062373 IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").
25072374
2375 minLength: 1
2376
25082377 - `type: "cron"`
25092378
2510 - `"cron"`
2511
25122379 - `last_run_at: optional string or null`
25132380
25142381 A timestamp in RFC 3339 format
25152382
2383 format: date-time
2384
25162385 - `upcoming_runs_at: optional array of string`
25172386
25182387 Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.
from line 2396
25272396
25282397 - `type: "deployment"`
25292398
2530 - `"deployment"`
2531
25322399 - `updated_at: string`
25332400
25342401 A timestamp in RFC 3339 format
25352402
2403 format: date-time
2404
25362405 - `vault_ids: array of string`
25372406
25382407 Vault IDs supplying stored credentials for sessions created from this deployment.
from line 2422
25532422
25542423 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.
25552424
2556 - `"USD"`
2557
25582425 - `type: "limit"`
25592426
2560 - `"limit"`
2561
25622427### Example
25632428
2564```http
2429```bash
25652430curl https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID \
25662431 -H 'anthropic-version: 2023-06-01' \
25672432 -H 'anthropic-beta: managed-agents-2026-04-01' \
25682433 -H "X-Api-Key: $ANTHROPIC_API_KEY"
25692434```
25702435
2571#### Response
2436#### Response (200)
25722437
25732438```json
25742439{
from line 2502
26372502
26382503## Update Deployment
26392504
2640**post** `/v1/deployments/{deployment_id}`
2505**POST** `/v1/deployments/{deployment_id}`
26412506
26422507Update Deployment
26432508
2644### Path Parameters
2509### Path parameters
26452510
26462511- `deployment_id: string`
26472512
2648### Header Parameters
2513### Headers
26492514
26502515- `"anthropic-beta": optional array of AnthropicBeta`
26512516
from line 2588
27232588
27242589 - `"mid-conversation-tool-changes-2026-07-01"`
27252590
2726### Body Parameters
2591### Body parameters
27272592
27282593- `agent: optional string or BetaManagedAgentsAgentParams`
27292594
from line 2596
27312596
27322597 - `string`
27332598
2734 - `BetaManagedAgentsAgentParams object { id, type, version }`
2599 - `BetaManagedAgentsAgentParams object`
27352600
27362601 Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version
27372602
from line 2604
27392604
27402605 The `agent` ID.
27412606
2607 minLength: 1, maxLength: 128
2608
27422609 - `type: "agent"`
27432610
2744 - `"agent"`
2745
27462611 - `version: optional number`
27472612
27482613 The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.
27492614
2615 format: int32
2616
27502617- `budget: optional BetaManagedAgentsBudgetLimit or null`
27512618
27522619 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 2630
27632630
27642631 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.
27652632
2766 - `"USD"`
2767
27682633 - `type: "limit"`
27692634
2770 - `"limit"`
2771
27722635- `description: optional string or null`
27732636
27742637 Description. Omit to preserve; send empty string or null to clear.
27752638
2639 maxLength: 2048
2640
27762641- `environment_id: optional string`
27772642
27782643 ID of the `environment` where sessions run. Omit to preserve. Cannot be cleared.
27792644
2645 maxLength: 128
2646
27802647- `initial_events: optional array of BetaManagedAgentsDeploymentInitialEventParams`
27812648
27822649 Initial events. Full replacement. Omit to preserve. Cannot be cleared. At least 1, maximum 50.
27832650
2784 - `BetaManagedAgentsUserMessageEventParams object { content, type }`
2651 - `BetaManagedAgentsUserMessageEventParams object`
27852652
27862653 Parameters for sending a user message to the session.
27872654
from line 2656
27892656
27902657 Array of content blocks for the user message.
27912658
2792 - `BetaManagedAgentsTextBlock object { text, type }`
2659 - `BetaManagedAgentsTextBlock object`
27932660
27942661 Regular text content.
27952662
from line 2664
27972664
27982665 The text content.
27992666
2667 minLength: 1
2668
28002669 - `type: "text"`
28012670
2802 - `"text"`
2803
2804 - `BetaManagedAgentsImageBlock object { source, type }`
2671 - `BetaManagedAgentsImageBlock object`
28052672
28062673 Image content specified directly as base64 data or as a reference via a URL.
28072674
from line 2676
28092676
28102677 Union type for image source variants.
28112678
2812 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
2679 - `BetaManagedAgentsBase64ImageSource object`
28132680
28142681 Base64-encoded image data.
28152682
from line 2684
28172684
28182685 Base64-encoded image data.
28192686
2687 minLength: 1
2688
28202689 - `media_type: string`
28212690
28222691 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
28232692
2693 minLength: 1
2694
28242695 - `type: "base64"`
28252696
2826 - `"base64"`
2827
2828 - `BetaManagedAgentsURLImageSource object { type, url }`
2697 - `BetaManagedAgentsURLImageSource object`
28292698
28302699 Image referenced by URL.
28312700
28322701 - `type: "url"`
28332702
2834 - `"url"`
2835
28362703 - `url: string`
28372704
28382705 URL of the image to fetch.
28392706
2840 - `BetaManagedAgentsFileImageSource object { file_id, type }`
2707 minLength: 1
2708
2709 - `BetaManagedAgentsFileImageSource object`
28412710
28422711 Image referenced by file ID.
28432712
from line 2714
28452714
28462715 ID of a previously uploaded file.
28472716
2717 minLength: 1
2718
28482719 - `type: "file"`
28492720
2850 - `"file"`
2851
28522721 - `type: "image"`
28532722
2854 - `"image"`
2855
2856 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
2723 - `BetaManagedAgentsDocumentBlock object`
28572724
28582725 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
28592726
from line 2728
28612728
28622729 Union type for document source variants.
28632730
2864 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
2731 - `BetaManagedAgentsBase64DocumentSource object`
28652732
28662733 Base64-encoded document data.
28672734
from line 2736
28692736
28702737 Base64-encoded document data.
28712738
2739 minLength: 1
2740
28722741 - `media_type: string`
28732742
28742743 MIME type of the document (e.g., "application/pdf").
28752744
2745 minLength: 1
2746
28762747 - `type: "base64"`
28772748
2878 - `"base64"`
2879
2880 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
2749 - `BetaManagedAgentsPlainTextDocumentSource object`
28812750
28822751 Plain text document content.
28832752
from line 2754
28852754
28862755 The plain text content.
28872756
2757 minLength: 1
2758
28882759 - `media_type: "text/plain"`
28892760
28902761 MIME type of the text content. Must be "text/plain".
28912762
2892 - `"text/plain"`
2893
28942763 - `type: "text"`
28952764
2896 - `"text"`
2897
2898 - `BetaManagedAgentsURLDocumentSource object { type, url }`
2765 - `BetaManagedAgentsURLDocumentSource object`
28992766
29002767 Document referenced by URL.
29012768
29022769 - `type: "url"`
29032770
2904 - `"url"`
2905
29062771 - `url: string`
29072772
29082773 URL of the document to fetch.
29092774
2910 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
2775 minLength: 1
2776
2777 - `BetaManagedAgentsFileDocumentSource object`
29112778
29122779 Document referenced by file ID.
29132780
from line 2782
29152782
29162783 ID of a previously uploaded file.
29172784
2785 minLength: 1
2786
29182787 - `type: "file"`
29192788
2920 - `"file"`
2921
29222789 - `type: "document"`
29232790
2924 - `"document"`
2925
29262791 - `context: optional string or null`
29272792
29282793 Additional context about the document for the model.
from line 2796
29312796
29322797 The title of the document.
29332798
2934 - `BetaManagedAgentsRedactedBlock object { type }`
2799 - `BetaManagedAgentsRedactedBlock object`
29352800
29362801 Placeholder for content withheld by Anthropic model policy.
29372802
29382803 - `type: "redacted"`
29392804
2940 - `"redacted"`
2941
29422805 - `type: "user.message"`
29432806
2944 - `"user.message"`
2945
2946 - `BetaManagedAgentsUserDefineOutcomeEventParams object { description, rubric, type, max_iterations }`
2807 - `BetaManagedAgentsUserDefineOutcomeEventParams object`
29472808
29482809 Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.
29492810
from line 2816
29552816
29562817 Rubric for grading the quality of an outcome.
29572818
2958 - `BetaManagedAgentsFileRubricParams object { file_id, type }`
2819 - `BetaManagedAgentsFileRubricParams object`
29592820
29602821 Rubric referenced by a file uploaded via the Files API.
29612822
from line 2826
29652826
29662827 - `type: "file"`
29672828
2968 - `"file"`
2969
2970 - `BetaManagedAgentsTextRubricParams object { content, type }`
2829 - `BetaManagedAgentsTextRubricParams object`
29712830
29722831 Rubric content provided inline as text.
29732832
from line 2834
29752834
29762835 Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.
29772836
2837 maxLength: 262144
2838
29782839 - `type: "text"`
29792840
2980 - `"text"`
2981
29822841 - `type: "user.define_outcome"`
29832842
2984 - `"user.define_outcome"`
2985
29862843 - `max_iterations: optional number or null`
29872844
29882845 Eval→revision cycles before giving up. Default 3, max 20.
29892846
2990 - `BetaManagedAgentsSystemMessageEventParams object { content, type }`
2847 format: int32
2848
2849 - `BetaManagedAgentsSystemMessageEventParams object`
29912850
29922851 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.
29932852
from line 2858
29992858
30002859 The text content.
30012860
2861 minLength: 1
2862
30022863 - `type: "text"`
30032864
3004 - `"text"`
3005
30062865 - `type: "system.message"`
30072866
3008 - `"system.message"`
3009
30102867- `metadata: optional map[string] or null`
30112868
30122869 Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars.
from line 2872
30152872
30162873 Human-readable name. Must be non-empty. Omit to preserve. Cannot be cleared.
30172874
2875 maxLength: 256
2876
30182877- `resources: optional array of BetaManagedAgentsGitHubRepositoryResourceParams or BetaManagedAgentsFileResourceParams or BetaManagedAgentsMemoryStoreResourceParam or null`
30192878
30202879 Session resources. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 500.
30212880
3022 - `BetaManagedAgentsGitHubRepositoryResourceParams object { authorization_token, type, url, 2 more }`
2881 - `BetaManagedAgentsGitHubRepositoryResourceParams object`
30232882
30242883 Mount a GitHub repository into the session's container.
30252884
from line 2886
30272886
30282887 GitHub authorization token used to clone the repository.
30292888
2889 minLength: 1, maxLength: 4096
2890
30302891 - `type: "github_repository"`
30312892
3032 - `"github_repository"`
3033
30342893 - `url: string`
30352894
30362895 Github URL of the repository
30372896
2897 minLength: 1, maxLength: 2048
2898
30382899 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
30392900
30402901 Branch or commit to check out. Defaults to the repository's default branch.
30412902
3042 - `BetaManagedAgentsBranchCheckout object { name, type }`
2903 - `BetaManagedAgentsBranchCheckout object`
30432904
30442905 - `name: string`
30452906
30462907 Branch name to check out.
30472908
2909 minLength: 1, maxLength: 255
2910
30482911 - `type: "branch"`
30492912
3050 - `"branch"`
3051
3052 - `BetaManagedAgentsCommitCheckout object { sha, type }`
2913 - `BetaManagedAgentsCommitCheckout object`
30532914
30542915 - `sha: string`
30552916
30562917 Full commit SHA to check out.
30572918
2919 minLength: 7, maxLength: 64
2920
30582921 - `type: "commit"`
30592922
3060 - `"commit"`
3061
30622923 - `mount_path: optional string or null`
30632924
30642925 Mount path in the container. Defaults to `/workspace/<repo-name>`.
30652926
3066 - `BetaManagedAgentsFileResourceParams object { file_id, type, mount_path }`
2927 minLength: 1, maxLength: 4096
2928
2929 - `BetaManagedAgentsFileResourceParams object`
30672930
30682931 Mount a file uploaded via the Files API into the session.
30692932
from line 2934
30712934
30722935 ID of a previously uploaded file.
30732936
2937 minLength: 1, maxLength: 128
2938
30742939 - `type: "file"`
30752940
3076 - `"file"`
3077
30782941 - `mount_path: optional string or null`
30792942
30802943 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
30812944
3082 - `BetaManagedAgentsMemoryStoreResourceParam object { memory_store_id, type, access, instructions }`
2945 minLength: 1, maxLength: 4096
2946
2947 - `BetaManagedAgentsMemoryStoreResourceParam object`
30832948
30842949 Parameters for attaching a memory store to an agent session.
30852950
from line 2954
30892954
30902955 - `type: "memory_store"`
30912956
3092 - `"memory_store"`
3093
30942957 - `access: optional "read_write" or "read_only" or null`
30952958
30962959 Access mode for an attached memory store.
from line 2966
31032966
31042967 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
31052968
2969 maxLength: 4096
2970
31062971- `schedule: optional BetaManagedAgentsScheduleParams or null`
31072972
31082973 5-field POSIX cron schedule. Literal wall-clock matching in the configured timezone.
from line 2976
31112976
31122977 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).
31132978
2979 minLength: 1, maxLength: 256
2980
31142981 - `timezone: string`
31152982
31162983 Required. IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). Validated against the IANA timezone database.
31172984
2985 minLength: 1
2986
31182987 - `type: "cron"`
31192988
3120 - `"cron"`
3121
31222989- `vault_ids: optional array of string or null`
31232990
31242991 Vault IDs. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 50.
31252992
31262993### Returns
31272994
3128- `BetaManagedAgentsDeployment object { id, agent, archived_at, 14 more }`
2995- `BetaManagedAgentsDeployment object`
31292996
31302997 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.
31312998
from line 3008
31413008
31423009 - `type: "agent"`
31433010
3144 - `"agent"`
3145
31463011 - `version: number`
31473012
3013 format: int32
3014
31483015 - `archived_at: string or null`
31493016
31503017 A timestamp in RFC 3339 format
31513018
3019 format: date-time
3020
31523021 - `created_at: string`
31533022
31543023 A timestamp in RFC 3339 format
31553024
3025 format: date-time
3026
31563027 - `description: string or null`
31573028
31583029 Description of what the deployment does.
from line 3036
31653036
31663037 Events sent to each session immediately after creation.
31673038
3168 - `BetaManagedAgentsDeploymentUserMessageEvent object { content, type }`
3039 - `BetaManagedAgentsDeploymentUserMessageEvent object`
31693040
31703041 A user message sent to the session.
31713042
from line 3044
31733044
31743045 Array of content blocks for the user message.
31753046
3176 - `BetaManagedAgentsTextBlock object { text, type }`
3047 - `BetaManagedAgentsTextBlock object`
31773048
31783049 Regular text content.
31793050
from line 3052
31813052
31823053 The text content.
31833054
3055 minLength: 1
3056
31843057 - `type: "text"`
31853058
3186 - `"text"`
3187
3188 - `BetaManagedAgentsImageBlock object { source, type }`
3059 - `BetaManagedAgentsImageBlock object`
31893060
31903061 Image content specified directly as base64 data or as a reference via a URL.
31913062
from line 3064
31933064
31943065 Union type for image source variants.
31953066
3196 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
3067 - `BetaManagedAgentsBase64ImageSource object`
31973068
31983069 Base64-encoded image data.
31993070
from line 3072
32013072
32023073 Base64-encoded image data.
32033074
3075 minLength: 1
3076
32043077 - `media_type: string`
32053078
32063079 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
32073080
3081 minLength: 1
3082
32083083 - `type: "base64"`
32093084
3210 - `"base64"`
3211
3212 - `BetaManagedAgentsURLImageSource object { type, url }`
3085 - `BetaManagedAgentsURLImageSource object`
32133086
32143087 Image referenced by URL.
32153088
32163089 - `type: "url"`
32173090
3218 - `"url"`
3219
32203091 - `url: string`
32213092
32223093 URL of the image to fetch.
32233094
3224 - `BetaManagedAgentsFileImageSource object { file_id, type }`
3095 minLength: 1
3096
3097 - `BetaManagedAgentsFileImageSource object`
32253098
32263099 Image referenced by file ID.
32273100
from line 3102
32293102
32303103 ID of a previously uploaded file.
32313104
3105 minLength: 1
3106
32323107 - `type: "file"`
32333108
3234 - `"file"`
3235
32363109 - `type: "image"`
32373110
3238 - `"image"`
3239
3240 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
3111 - `BetaManagedAgentsDocumentBlock object`
32413112
32423113 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
32433114
from line 3116
32453116
32463117 Union type for document source variants.
32473118
3248 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
3119 - `BetaManagedAgentsBase64DocumentSource object`
32493120
32503121 Base64-encoded document data.
32513122
from line 3124
32533124
32543125 Base64-encoded document data.
32553126
3127 minLength: 1
3128
32563129 - `media_type: string`
32573130
32583131 MIME type of the document (e.g., "application/pdf").
32593132
3133 minLength: 1
3134
32603135 - `type: "base64"`
32613136
3262 - `"base64"`
3263
3264 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
3137 - `BetaManagedAgentsPlainTextDocumentSource object`
32653138
32663139 Plain text document content.
32673140
from line 3142
32693142
32703143 The plain text content.
32713144
3145 minLength: 1
3146
32723147 - `media_type: "text/plain"`
32733148
32743149 MIME type of the text content. Must be "text/plain".
32753150
3276 - `"text/plain"`
3277
32783151 - `type: "text"`
32793152
3280 - `"text"`
3281
3282 - `BetaManagedAgentsURLDocumentSource object { type, url }`
3153 - `BetaManagedAgentsURLDocumentSource object`
32833154
32843155 Document referenced by URL.
32853156
32863157 - `type: "url"`
32873158
3288 - `"url"`
3289
32903159 - `url: string`
32913160
32923161 URL of the document to fetch.
32933162
3294 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
3163 minLength: 1
3164
3165 - `BetaManagedAgentsFileDocumentSource object`
32953166
32963167 Document referenced by file ID.
32973168
from line 3170
32993170
33003171 ID of a previously uploaded file.
33013172
3173 minLength: 1
3174
33023175 - `type: "file"`
33033176
3304 - `"file"`
3305
33063177 - `type: "document"`
33073178
3308 - `"document"`
3309
33103179 - `context: optional string or null`
33113180
33123181 Additional context about the document for the model.
from line 3184
33153184
33163185 The title of the document.
33173186
3318 - `BetaManagedAgentsRedactedBlock object { type }`
3187 - `BetaManagedAgentsRedactedBlock object`
33193188
33203189 Placeholder for content withheld by Anthropic model policy.
33213190
33223191 - `type: "redacted"`
33233192
3324 - `"redacted"`
3325
33263193 - `type: "user.message"`
33273194
3328 - `"user.message"`
3329
3330 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object { description, rubric, type, max_iterations }`
3195 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`
33313196
33323197 An outcome the agent should work toward. The agent begins work on receipt.
33333198
from line 3204
33393204
33403205 Rubric for grading the quality of an outcome.
33413206
3342 - `BetaManagedAgentsFileRubric object { file_id, type }`
3207 - `BetaManagedAgentsFileRubric object`
33433208
33443209 Rubric referenced by a file uploaded via the Files API.
33453210
from line 3214
33493214
33503215 - `type: "file"`
33513216
3352 - `"file"`
3353
3354 - `BetaManagedAgentsTextRubric object { content, type }`
3217 - `BetaManagedAgentsTextRubric object`
33553218
33563219 Rubric content provided inline as text.
33573220
from line 3224
33613224
33623225 - `type: "text"`
33633226
3364 - `"text"`
3365
33663227 - `type: "user.define_outcome"`
33673228
3368 - `"user.define_outcome"`
3369
33703229 - `max_iterations: optional number or null`
33713230
33723231 Eval→revision cycles before giving up. Default 3, max 20.
33733232
3374 - `BetaManagedAgentsDeploymentSystemMessageEvent object { content, type }`
3233 format: int32
3234
3235 - `BetaManagedAgentsDeploymentSystemMessageEvent object`
33753236
33763237 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.
33773238
from line 3244
33833244
33843245 The text content.
33853246
3247 minLength: 1
3248
33863249 - `type: "text"`
33873250
3388 - `"text"`
3389
33903251 - `type: "system.message"`
33913252
3392 - `"system.message"`
3393
33943253 - `metadata: map[string]`
33953254
33963255 Arbitrary key-value metadata. Maximum 16 pairs.
from line 3262
34033262
34043263 Why a deployment is paused. Non-null exactly when `status` is `paused`.
34053264
3406 - `BetaManagedAgentsManualDeploymentPausedReason object { type }`
3265 - `BetaManagedAgentsManualDeploymentPausedReason object`
34073266
34083267 The caller invoked the pause endpoint on the deployment.
34093268
34103269 - `type: "manual"`
34113270
3412 - `"manual"`
3413
3414 - `BetaManagedAgentsErrorDeploymentPausedReason object { error, type }`
3271 - `BetaManagedAgentsErrorDeploymentPausedReason object`
34153272
34163273 A scheduled fire recorded a failed run whose error auto-pauses the deployment.
34173274
from line 3276
34193276
34203277 The error that triggered an auto-pause. Matches the failed run's `error.type`.
34213278
3422 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object { type }`
3279 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object`
34233280
34243281 The deployment's environment was archived.
34253282
34263283 - `type: "environment_archived_error"`
34273284
3428 - `"environment_archived_error"`
3429
3430 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object { type }`
3285 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object`
34313286
34323287 The deployment's agent was archived.
34333288
34343289 - `type: "agent_archived_error"`
34353290
3436 - `"agent_archived_error"`
3437
3438 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object { type }`
3291 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object`
34393292
34403293 The deployment's environment no longer exists.
34413294
34423295 - `type: "environment_not_found_error"`
34433296
3444 - `"environment_not_found_error"`
3445
3446 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object { type }`
3297 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object`
34473298
34483299 A vault referenced by the deployment no longer exists.
34493300
34503301 - `type: "vault_not_found_error"`
34513302
3452 - `"vault_not_found_error"`
3453
3454 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object { type }`
3303 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object`
34553304
34563305 A file resource referenced by the deployment no longer exists.
34573306
34583307 - `type: "file_not_found_error"`
34593308
3460 - `"file_not_found_error"`
3461
3462 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object { type }`
3309 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object`
34633310
34643311 A referenced resource no longer exists and its kind was not reported.
34653312
34663313 - `type: "session_resource_not_found_error"`
34673314
3468 - `"session_resource_not_found_error"`
3469
3470 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object { type }`
3315 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object`
34713316
34723317 The deployment's workspace was archived.
34733318
34743319 - `type: "workspace_archived_error"`
34753320
3476 - `"workspace_archived_error"`
3477
3478 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object { type }`
3321 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object`
34793322
34803323 The deployment's organization is disabled.
34813324
34823325 - `type: "organization_disabled_error"`
34833326
3484 - `"organization_disabled_error"`
3485
3486 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object { type }`
3327 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object`
34873328
34883329 A memory store referenced by the deployment is archived.
34893330
34903331 - `type: "memory_store_archived_error"`
34913332
3492 - `"memory_store_archived_error"`
3493
3494 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object { type }`
3333 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object`
34953334
34963335 A skill referenced by the deployment's agent no longer exists.
34973336
34983337 - `type: "skill_not_found_error"`
34993338
3500 - `"skill_not_found_error"`
3501
3502 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object { type }`
3339 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object`
35033340
35043341 A vault referenced by the deployment is archived.
35053342
35063343 - `type: "vault_archived_error"`
35073344
3508 - `"vault_archived_error"`
3509
3510 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object { type }`
3345 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object`
35113346
35123347 An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.
35133348
35143349 - `type: "unknown_error"`
35153350
3516 - `"unknown_error"`
3517
3518 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object { type }`
3351 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object`
35193352
35203353 The deployment configures resources, but its environment is self-hosted and cannot mount them.
35213354
35223355 - `type: "self_hosted_resources_unsupported_error"`
35233356
3524 - `"self_hosted_resources_unsupported_error"`
3525
3526 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object { type }`
3357 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object`
35273358
35283359 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
35293360
35303361 - `type: "mcp_egress_blocked_error"`
35313362
3532 - `"mcp_egress_blocked_error"`
3533
35343363 - `type: "error"`
35353364
3536 - `"error"`
3537
35383365 - `resources: array of BetaManagedAgentsSessionResourceConfig`
35393366
35403367 Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.
35413368
3542 - `BetaManagedAgentsGitHubRepositoryResourceConfig object { type, url, checkout, mount_path }`
3369 - `BetaManagedAgentsGitHubRepositoryResourceConfig object`
35433370
35443371 A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.
35453372
35463373 - `type: "github_repository"`
35473374
3548 - `"github_repository"`
3549
35503375 - `url: string`
35513376
35523377 Github URL of the repository
from line 3380
35553380
35563381 Branch or commit to check out. Defaults to the repository's default branch.
35573382
3558 - `BetaManagedAgentsBranchCheckout object { name, type }`
3383 - `BetaManagedAgentsBranchCheckout object`
35593384
35603385 - `name: string`
35613386
35623387 Branch name to check out.
35633388
3389 minLength: 1, maxLength: 255
3390
35643391 - `type: "branch"`
35653392
3566 - `"branch"`
3567
3568 - `BetaManagedAgentsCommitCheckout object { sha, type }`
3393 - `BetaManagedAgentsCommitCheckout object`
35693394
35703395 - `sha: string`
35713396
35723397 Full commit SHA to check out.
35733398
3399 minLength: 7, maxLength: 64
3400
35743401 - `type: "commit"`
35753402
3576 - `"commit"`
3577
35783403 - `mount_path: optional string or null`
35793404
35803405 Mount path in the container. Defaults to `/workspace/<repo-name>`.
35813406
3582 - `BetaManagedAgentsFileResourceConfig object { file_id, type, mount_path }`
3407 - `BetaManagedAgentsFileResourceConfig object`
35833408
35843409 A file mounted into each session's container.
35853410
from line 3414
35893414
35903415 - `type: "file"`
35913416
3592 - `"file"`
3593
35943417 - `mount_path: optional string or null`
35953418
35963419 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
35973420
3598 - `BetaManagedAgentsMemoryStoreResourceConfig object { memory_store_id, type, access, instructions }`
3421 - `BetaManagedAgentsMemoryStoreResourceConfig object`
35993422
36003423 A memory store attached to each session created from this deployment.
36013424
from line 3428
36053428
36063429 - `type: "memory_store"`
36073430
3608 - `"memory_store"`
3609
36103431 - `access: optional "read_write" or "read_only" or null`
36113432
36123433 Access mode for an attached memory store.
from line 3448
36273448
36283449 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).
36293450
3451 minLength: 1, maxLength: 256
3452
36303453 - `timezone: string`
36313454
36323455 IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").
36333456
3457 minLength: 1
3458
36343459 - `type: "cron"`
36353460
3636 - `"cron"`
3637
36383461 - `last_run_at: optional string or null`
36393462
36403463 A timestamp in RFC 3339 format
36413464
3465 format: date-time
3466
36423467 - `upcoming_runs_at: optional array of string`
36433468
36443469 Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.
from line 3478
36533478
36543479 - `type: "deployment"`
36553480
3656 - `"deployment"`
3657
36583481 - `updated_at: string`
36593482
36603483 A timestamp in RFC 3339 format
36613484
3485 format: date-time
3486
36623487 - `vault_ids: array of string`
36633488
36643489 Vault IDs supplying stored credentials for sessions created from this deployment.
from line 3504
36793504
36803505 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.
36813506
3682 - `"USD"`
3683
36843507 - `type: "limit"`
36853508
3686 - `"limit"`
3687
36883509### Example
36893510
3690```http
3511```bash
36913512curl https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID \
36923513 -H 'Content-Type: application/json' \
36933514 -H 'anthropic-version: 2023-06-01' \
from line 3517
36963517 -d '{}'
36973518```
36983519
3699#### Response
3520#### Response (200)
37003521
37013522```json
37023523{
from line 3586
37653586
37663587## Archive Deployment
37673588
3768**post** `/v1/deployments/{deployment_id}/archive`
3589**POST** `/v1/deployments/{deployment_id}/archive`
37693590
37703591Archive Deployment
37713592
3772### Path Parameters
3593### Path parameters
37733594
37743595- `deployment_id: string`
37753596
3776### Header Parameters
3597### Headers
37773598
37783599- `"anthropic-beta": optional array of AnthropicBeta`
37793600
from line 3674
38533674
38543675### Returns
38553676
3856- `BetaManagedAgentsDeployment object { id, agent, archived_at, 14 more }`
3677- `BetaManagedAgentsDeployment object`
38573678
38583679 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.
38593680
from line 3690
38693690
38703691 - `type: "agent"`
38713692
3872 - `"agent"`
3873
38743693 - `version: number`
38753694
3695 format: int32
3696
38763697 - `archived_at: string or null`
38773698
38783699 A timestamp in RFC 3339 format
38793700
3701 format: date-time
3702
38803703 - `created_at: string`
38813704
38823705 A timestamp in RFC 3339 format
38833706
3707 format: date-time
3708
38843709 - `description: string or null`
38853710
38863711 Description of what the deployment does.
from line 3718
38933718
38943719 Events sent to each session immediately after creation.
38953720
3896 - `BetaManagedAgentsDeploymentUserMessageEvent object { content, type }`
3721 - `BetaManagedAgentsDeploymentUserMessageEvent object`
38973722
38983723 A user message sent to the session.
38993724
from line 3726
39013726
39023727 Array of content blocks for the user message.
39033728
3904 - `BetaManagedAgentsTextBlock object { text, type }`
3729 - `BetaManagedAgentsTextBlock object`
39053730
39063731 Regular text content.
39073732
from line 3734
39093734
39103735 The text content.
39113736
3737 minLength: 1
3738
39123739 - `type: "text"`
39133740
3914 - `"text"`
3915
3916 - `BetaManagedAgentsImageBlock object { source, type }`
3741 - `BetaManagedAgentsImageBlock object`
39173742
39183743 Image content specified directly as base64 data or as a reference via a URL.
39193744
from line 3746
39213746
39223747 Union type for image source variants.
39233748
3924 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
3749 - `BetaManagedAgentsBase64ImageSource object`
39253750
39263751 Base64-encoded image data.
39273752
from line 3754
39293754
39303755 Base64-encoded image data.
39313756
3757 minLength: 1
3758
39323759 - `media_type: string`
39333760
39343761 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
39353762
3763 minLength: 1
3764
39363765 - `type: "base64"`
39373766
3938 - `"base64"`
3939
3940 - `BetaManagedAgentsURLImageSource object { type, url }`
3767 - `BetaManagedAgentsURLImageSource object`
39413768
39423769 Image referenced by URL.
39433770
39443771 - `type: "url"`
39453772
3946 - `"url"`
3947
39483773 - `url: string`
39493774
39503775 URL of the image to fetch.
39513776
3952 - `BetaManagedAgentsFileImageSource object { file_id, type }`
3777 minLength: 1
3778
3779 - `BetaManagedAgentsFileImageSource object`
39533780
39543781 Image referenced by file ID.
39553782
from line 3784
39573784
39583785 ID of a previously uploaded file.
39593786
3787 minLength: 1
3788
39603789 - `type: "file"`
39613790
3962 - `"file"`
3963
39643791 - `type: "image"`
39653792
3966 - `"image"`
3967
3968 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
3793 - `BetaManagedAgentsDocumentBlock object`
39693794
39703795 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
39713796
from line 3798
39733798
39743799 Union type for document source variants.
39753800
3976 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
3801 - `BetaManagedAgentsBase64DocumentSource object`
39773802
39783803 Base64-encoded document data.
39793804
from line 3806
39813806
39823807 Base64-encoded document data.
39833808
3809 minLength: 1
3810
39843811 - `media_type: string`
39853812
39863813 MIME type of the document (e.g., "application/pdf").
39873814
3815 minLength: 1
3816
39883817 - `type: "base64"`
39893818
3990 - `"base64"`
3991
3992 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
3819 - `BetaManagedAgentsPlainTextDocumentSource object`
39933820
39943821 Plain text document content.
39953822
from line 3824
39973824
39983825 The plain text content.
39993826
3827 minLength: 1
3828
40003829 - `media_type: "text/plain"`
40013830
40023831 MIME type of the text content. Must be "text/plain".
40033832
4004 - `"text/plain"`
4005
40063833 - `type: "text"`
40073834
4008 - `"text"`
4009
4010 - `BetaManagedAgentsURLDocumentSource object { type, url }`
3835 - `BetaManagedAgentsURLDocumentSource object`
40113836
40123837 Document referenced by URL.
40133838
40143839 - `type: "url"`
40153840
4016 - `"url"`
4017
40183841 - `url: string`
40193842
40203843 URL of the document to fetch.
40213844
4022 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
3845 minLength: 1
3846
3847 - `BetaManagedAgentsFileDocumentSource object`
40233848
40243849 Document referenced by file ID.
40253850
from line 3852
40273852
40283853 ID of a previously uploaded file.
40293854
3855 minLength: 1
3856
40303857 - `type: "file"`
40313858
4032 - `"file"`
4033
40343859 - `type: "document"`
40353860
4036 - `"document"`
4037
40383861 - `context: optional string or null`
40393862
40403863 Additional context about the document for the model.
from line 3866
40433866
40443867 The title of the document.
40453868
4046 - `BetaManagedAgentsRedactedBlock object { type }`
3869 - `BetaManagedAgentsRedactedBlock object`
40473870
40483871 Placeholder for content withheld by Anthropic model policy.
40493872
40503873 - `type: "redacted"`
40513874
4052 - `"redacted"`
4053
40543875 - `type: "user.message"`
40553876
4056 - `"user.message"`
4057
4058 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object { description, rubric, type, max_iterations }`
3877 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`
40593878
40603879 An outcome the agent should work toward. The agent begins work on receipt.
40613880
from line 3886
40673886
40683887 Rubric for grading the quality of an outcome.
40693888
4070 - `BetaManagedAgentsFileRubric object { file_id, type }`
3889 - `BetaManagedAgentsFileRubric object`
40713890
40723891 Rubric referenced by a file uploaded via the Files API.
40733892
from line 3896
40773896
40783897 - `type: "file"`
40793898
4080 - `"file"`
4081
4082 - `BetaManagedAgentsTextRubric object { content, type }`
3899 - `BetaManagedAgentsTextRubric object`
40833900
40843901 Rubric content provided inline as text.
40853902
from line 3906
40893906
40903907 - `type: "text"`
40913908
4092 - `"text"`
4093
40943909 - `type: "user.define_outcome"`
40953910
4096 - `"user.define_outcome"`
4097
40983911 - `max_iterations: optional number or null`
40993912
41003913 Eval→revision cycles before giving up. Default 3, max 20.
41013914
4102 - `BetaManagedAgentsDeploymentSystemMessageEvent object { content, type }`
3915 format: int32
3916
3917 - `BetaManagedAgentsDeploymentSystemMessageEvent object`
41033918
41043919 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.
41053920
from line 3926
41113926
41123927 The text content.
41133928
3929 minLength: 1
3930
41143931 - `type: "text"`
41153932
4116 - `"text"`
4117
41183933 - `type: "system.message"`
41193934
4120 - `"system.message"`
4121
41223935 - `metadata: map[string]`
41233936
41243937 Arbitrary key-value metadata. Maximum 16 pairs.
from line 3944
41313944
41323945 Why a deployment is paused. Non-null exactly when `status` is `paused`.
41333946
4134 - `BetaManagedAgentsManualDeploymentPausedReason object { type }`
3947 - `BetaManagedAgentsManualDeploymentPausedReason object`
41353948
41363949 The caller invoked the pause endpoint on the deployment.
41373950
41383951 - `type: "manual"`
41393952
4140 - `"manual"`
4141
4142 - `BetaManagedAgentsErrorDeploymentPausedReason object { error, type }`
3953 - `BetaManagedAgentsErrorDeploymentPausedReason object`
41433954
41443955 A scheduled fire recorded a failed run whose error auto-pauses the deployment.
41453956
from line 3958
41473958
41483959 The error that triggered an auto-pause. Matches the failed run's `error.type`.
41493960
4150 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object { type }`
3961 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object`
41513962
41523963 The deployment's environment was archived.
41533964
41543965 - `type: "environment_archived_error"`
41553966
4156 - `"environment_archived_error"`
4157
4158 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object { type }`
3967 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object`
41593968
41603969 The deployment's agent was archived.
41613970
41623971 - `type: "agent_archived_error"`
41633972
4164 - `"agent_archived_error"`
4165
4166 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object { type }`
3973 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object`
41673974
41683975 The deployment's environment no longer exists.
41693976
41703977 - `type: "environment_not_found_error"`
41713978
4172 - `"environment_not_found_error"`
4173
4174 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object { type }`
3979 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object`
41753980
41763981 A vault referenced by the deployment no longer exists.
41773982
41783983 - `type: "vault_not_found_error"`
41793984
4180 - `"vault_not_found_error"`
4181
4182 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object { type }`
3985 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object`
41833986
41843987 A file resource referenced by the deployment no longer exists.
41853988
41863989 - `type: "file_not_found_error"`
41873990
4188 - `"file_not_found_error"`
4189
4190 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object { type }`
3991 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object`
41913992
41923993 A referenced resource no longer exists and its kind was not reported.
41933994
41943995 - `type: "session_resource_not_found_error"`
41953996
4196 - `"session_resource_not_found_error"`
4197
4198 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object { type }`
3997 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object`
41993998
42003999 The deployment's workspace was archived.
42014000
42024001 - `type: "workspace_archived_error"`
42034002
4204 - `"workspace_archived_error"`
4205
4206 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object { type }`
4003 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object`
42074004
42084005 The deployment's organization is disabled.
42094006
42104007 - `type: "organization_disabled_error"`
42114008
4212 - `"organization_disabled_error"`
4213
4214 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object { type }`
4009 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object`
42154010
42164011 A memory store referenced by the deployment is archived.
42174012
42184013 - `type: "memory_store_archived_error"`
42194014
4220 - `"memory_store_archived_error"`
4221
4222 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object { type }`
4015 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object`
42234016
42244017 A skill referenced by the deployment's agent no longer exists.
42254018
42264019 - `type: "skill_not_found_error"`
42274020
4228 - `"skill_not_found_error"`
4229
4230 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object { type }`
4021 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object`
42314022
42324023 A vault referenced by the deployment is archived.
42334024
42344025 - `type: "vault_archived_error"`
42354026
4236 - `"vault_archived_error"`
4237
4238 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object { type }`
4027 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object`
42394028
42404029 An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.
42414030
42424031 - `type: "unknown_error"`
42434032
4244 - `"unknown_error"`
4245
4246 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object { type }`
4033 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object`
42474034
42484035 The deployment configures resources, but its environment is self-hosted and cannot mount them.
42494036
42504037 - `type: "self_hosted_resources_unsupported_error"`
42514038
4252 - `"self_hosted_resources_unsupported_error"`
4253
4254 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object { type }`
4039 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object`
42554040
42564041 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
42574042
42584043 - `type: "mcp_egress_blocked_error"`
42594044
4260 - `"mcp_egress_blocked_error"`
4261
42624045 - `type: "error"`
42634046
4264 - `"error"`
4265
42664047 - `resources: array of BetaManagedAgentsSessionResourceConfig`
42674048
42684049 Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.
42694050
4270 - `BetaManagedAgentsGitHubRepositoryResourceConfig object { type, url, checkout, mount_path }`
4051 - `BetaManagedAgentsGitHubRepositoryResourceConfig object`
42714052
42724053 A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.
42734054
42744055 - `type: "github_repository"`
42754056
4276 - `"github_repository"`
4277
42784057 - `url: string`
42794058
42804059 Github URL of the repository
from line 4062
42834062
42844063 Branch or commit to check out. Defaults to the repository's default branch.
42854064
4286 - `BetaManagedAgentsBranchCheckout object { name, type }`
4065 - `BetaManagedAgentsBranchCheckout object`
42874066
42884067 - `name: string`
42894068
42904069 Branch name to check out.
42914070
4071 minLength: 1, maxLength: 255
4072
42924073 - `type: "branch"`
42934074
4294 - `"branch"`
4295
4296 - `BetaManagedAgentsCommitCheckout object { sha, type }`
4075 - `BetaManagedAgentsCommitCheckout object`
42974076
42984077 - `sha: string`
42994078
43004079 Full commit SHA to check out.
43014080
4081 minLength: 7, maxLength: 64
4082
43024083 - `type: "commit"`
43034084
4304 - `"commit"`
4305
43064085 - `mount_path: optional string or null`
43074086
43084087 Mount path in the container. Defaults to `/workspace/<repo-name>`.
43094088
4310 - `BetaManagedAgentsFileResourceConfig object { file_id, type, mount_path }`
4089 - `BetaManagedAgentsFileResourceConfig object`
43114090
43124091 A file mounted into each session's container.
43134092
from line 4096
43174096
43184097 - `type: "file"`
43194098
4320 - `"file"`
4321
43224099 - `mount_path: optional string or null`
43234100
43244101 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
43254102
4326 - `BetaManagedAgentsMemoryStoreResourceConfig object { memory_store_id, type, access, instructions }`
4103 - `BetaManagedAgentsMemoryStoreResourceConfig object`
43274104
43284105 A memory store attached to each session created from this deployment.
43294106
from line 4110
43334110
43344111 - `type: "memory_store"`
43354112
4336 - `"memory_store"`
4337
43384113 - `access: optional "read_write" or "read_only" or null`
43394114
43404115 Access mode for an attached memory store.
from line 4130
43554130
43564131 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).
43574132
4133 minLength: 1, maxLength: 256
4134
43584135 - `timezone: string`
43594136
43604137 IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").
43614138
4139 minLength: 1
4140
43624141 - `type: "cron"`
43634142
4364 - `"cron"`
4365
43664143 - `last_run_at: optional string or null`
43674144
43684145 A timestamp in RFC 3339 format
43694146
4147 format: date-time
4148
43704149 - `upcoming_runs_at: optional array of string`
43714150
43724151 Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.
from line 4160
43814160
43824161 - `type: "deployment"`
43834162
4384 - `"deployment"`
4385
43864163 - `updated_at: string`
43874164
43884165 A timestamp in RFC 3339 format
43894166
4167 format: date-time
4168
43904169 - `vault_ids: array of string`
43914170
43924171 Vault IDs supplying stored credentials for sessions created from this deployment.
from line 4186
44074186
44084187 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.
44094188
4410 - `"USD"`
4411
44124189 - `type: "limit"`
44134190
4414 - `"limit"`
4415
44164191### Example
44174192
4418```http
4193```bash
44194194curl https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/archive \
44204195 -X POST \
44214196 -H 'anthropic-version: 2023-06-01' \
from line 4198
44234198 -H "X-Api-Key: $ANTHROPIC_API_KEY"
44244199```
44254200
4426#### Response
4201#### Response (200)
44274202
44284203```json
44294204{
from line 4267
44924267
44934268## Run Deployment Now
44944269
4495**post** `/v1/deployments/{deployment_id}/run`
4270**POST** `/v1/deployments/{deployment_id}/run`
44964271
44974272Run Deployment Now
44984273
4499### Path Parameters
4274### Path parameters
45004275
45014276- `deployment_id: string`
45024277
4503### Header Parameters
4278### Headers
45044279
45054280- `"anthropic-beta": optional array of AnthropicBeta`
45064281
from line 4355
45804355
45814356### Returns
45824357
4583- `BetaManagedAgentsDeploymentRun object { id, agent, created_at, 5 more }`
4358- `BetaManagedAgentsDeploymentRun object`
45844359
45854360 A persistent, append-only record of a single deployment execution. Records session creation success or failure — no session lifecycle tracking.
45864361
from line 4371
45964371
45974372 - `type: "agent"`
45984373
4599 - `"agent"`
4600
46014374 - `version: number`
46024375
4376 format: int32
4377
46034378 - `created_at: string`
46044379
46054380 A timestamp in RFC 3339 format
46064381
4382 format: date-time
4383
46074384 - `deployment_id: string`
46084385
46094386 ID of the deployment that produced this run.
from line 4389
46124389
46134390 Why the run failed to create a session. The type identifies the failure; message is human-readable detail.
46144391
4615 - `BetaManagedAgentsEnvironmentArchivedRunError object { message, type }`
4392 - `BetaManagedAgentsEnvironmentArchivedRunError object`
46164393
46174394 The deployment's environment was archived.
46184395
from line 4399
46224399
46234400 - `type: "environment_archived_error"`
46244401
4625 - `"environment_archived_error"`
4626
4627 - `BetaManagedAgentsAgentArchivedRunError object { message, type }`
4402 - `BetaManagedAgentsAgentArchivedRunError object`
46284403
46294404 The deployment's agent was archived.
46304405
from line 4409
46344409
46354410 - `type: "agent_archived_error"`
46364411
4637 - `"agent_archived_error"`
4638
4639 - `BetaManagedAgentsEnvironmentNotFoundRunError object { message, type }`
4412 - `BetaManagedAgentsEnvironmentNotFoundRunError object`
46404413
46414414 The deployment's environment no longer exists.
46424415
from line 4419
46464419
46474420 - `type: "environment_not_found_error"`
46484421
4649 - `"environment_not_found_error"`
4650
4651 - `BetaManagedAgentsVaultNotFoundRunError object { message, type }`
4422 - `BetaManagedAgentsVaultNotFoundRunError object`
46524423
46534424 A vault referenced by the deployment no longer exists.
46544425
from line 4429
46584429
46594430 - `type: "vault_not_found_error"`
46604431
4661 - `"vault_not_found_error"`
4662
4663 - `BetaManagedAgentsVaultArchivedRunError object { message, type }`
4432 - `BetaManagedAgentsVaultArchivedRunError object`
46644433
46654434 A vault referenced by the deployment is archived.
46664435
from line 4439
46704439
46714440 - `type: "vault_archived_error"`
46724441
4673 - `"vault_archived_error"`
4674
4675 - `BetaManagedAgentsFileNotFoundRunError object { message, type }`
4442 - `BetaManagedAgentsFileNotFoundRunError object`
46764443
46774444 A file resource referenced by the deployment no longer exists.
46784445
from line 4449
46824449
46834450 - `type: "file_not_found_error"`
46844451
4685 - `"file_not_found_error"`
4686
4687 - `BetaManagedAgentsMemoryStoreArchivedRunError object { message, type }`
4452 - `BetaManagedAgentsMemoryStoreArchivedRunError object`
46884453
46894454 A memory store referenced by the deployment is archived.
46904455
from line 4459
46944459
46954460 - `type: "memory_store_archived_error"`
46964461
4697 - `"memory_store_archived_error"`
4698
4699 - `BetaManagedAgentsSkillNotFoundRunError object { message, type }`
4462 - `BetaManagedAgentsSkillNotFoundRunError object`
47004463
47014464 A skill referenced by the deployment's agent no longer exists.
47024465
from line 4469
47064469
47074470 - `type: "skill_not_found_error"`
47084471
4709 - `"skill_not_found_error"`
4710
4711 - `BetaManagedAgentsSessionResourceNotFoundRunError object { message, type }`
4472 - `BetaManagedAgentsSessionResourceNotFoundRunError object`
47124473
47134474 A referenced resource no longer exists and its kind was not reported.
47144475
from line 4479
47184479
47194480 - `type: "session_resource_not_found_error"`
47204481
4721 - `"session_resource_not_found_error"`
4722
4723 - `BetaManagedAgentsWorkspaceArchivedRunError object { message, type }`
4482 - `BetaManagedAgentsWorkspaceArchivedRunError object`
47244483
47254484 The deployment's workspace was archived.
47264485
from line 4489
47304489
47314490 - `type: "workspace_archived_error"`
47324491
4733 - `"workspace_archived_error"`
4734
4735 - `BetaManagedAgentsOrganizationDisabledRunError object { message, type }`
4492 - `BetaManagedAgentsOrganizationDisabledRunError object`
47364493
47374494 The deployment's organization is disabled.
47384495
from line 4499
47424499
47434500 - `type: "organization_disabled_error"`
47444501
4745 - `"organization_disabled_error"`
4746
4747 - `BetaManagedAgentsSessionRateLimitedRunError object { message, type }`
4502 - `BetaManagedAgentsSessionRateLimitedRunError object`
47484503
47494504 Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed.
47504505
from line 4509
47544509
47554510 - `type: "session_rate_limited_error"`
47564511
4757 - `"session_rate_limited_error"`
4758
4759 - `BetaManagedAgentsSessionCreationRejectedRunError object { message, type }`
4512 - `BetaManagedAgentsSessionCreationRejectedRunError object`
47604513
47614514 The session create request was rejected with a non-retryable validation error.
47624515
from line 4519
47664519
47674520 - `type: "session_creation_rejected_error"`
47684521
4769 - `"session_creation_rejected_error"`
4770
4771 - `BetaManagedAgentsUnknownRunError object { message, type }`
4522 - `BetaManagedAgentsUnknownRunError object`
47724523
47734524 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.
47744525
from line 4529
47784529
47794530 - `type: "unknown_error"`
47804531
4781 - `"unknown_error"`
4782
4783 - `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object { message, type }`
4532 - `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object`
47844533
47854534 The deployment configures resources, but its environment is self-hosted and cannot mount them.
47864535
from line 4539
47904539
47914540 - `type: "self_hosted_resources_unsupported_error"`
47924541
4793 - `"self_hosted_resources_unsupported_error"`
4794
4795 - `BetaManagedAgentsMCPEgressBlockedRunError object { message, type }`
4542 - `BetaManagedAgentsMCPEgressBlockedRunError object`
47964543
47974544 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
47984545
from line 4549
48024549
48034550 - `type: "mcp_egress_blocked_error"`
48044551
4805 - `"mcp_egress_blocked_error"`
4806
48074552 - `session_id: string or null`
48084553
48094554 Populated on success. Null on creation failure. Exactly one of session_id or error is non-null.
from line 4557
48124557
48134558 Describes what triggered a deployment run, with trigger-specific metadata.
48144559
4815 - `BetaManagedAgentsScheduleTriggerContext object { scheduled_at, type }`
4560 - `BetaManagedAgentsScheduleTriggerContext object`
48164561
48174562 The run was fired by the deployment's cron schedule.
48184563
from line 4565
48204565
48214566 A timestamp in RFC 3339 format
48224567
4568 format: date-time
4569
48234570 - `type: "schedule"`
48244571
4825 - `"schedule"`
4826
4827 - `BetaManagedAgentsManualTriggerContext object { type }`
4572 - `BetaManagedAgentsManualTriggerContext object`
48284573
48294574 The run was started manually by creating a session directly against the deployment.
48304575
48314576 - `type: "manual"`
48324577
4833 - `"manual"`
4834
48354578 - `type: "deployment_run"`
48364579
4837 - `"deployment_run"`
4838
48394580### Example
48404581
4841```http
4582```bash
48424583curl https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/run \
48434584 -X POST \
48444585 -H 'anthropic-version: 2023-06-01' \
from line 4587
48464587 -H "X-Api-Key: $ANTHROPIC_API_KEY"
48474588```
48484589
4849#### Response
4590#### Response (200)
48504591
48514592```json
48524593{
from line 4614
48734614
48744615## Pause Deployment
48754616
4876**post** `/v1/deployments/{deployment_id}/pause`
4617**POST** `/v1/deployments/{deployment_id}/pause`
48774618
48784619Pause Deployment
48794620
4880### Path Parameters
4621### Path parameters
48814622
48824623- `deployment_id: string`
48834624
4884### Header Parameters
4625### Headers
48854626
48864627- `"anthropic-beta": optional array of AnthropicBeta`
48874628
from line 4702
49614702
49624703### Returns
49634704
4964- `BetaManagedAgentsDeployment object { id, agent, archived_at, 14 more }`
4705- `BetaManagedAgentsDeployment object`
49654706
49664707 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.
49674708
from line 4718
49774718
49784719 - `type: "agent"`
49794720
4980 - `"agent"`
4981
49824721 - `version: number`
49834722
4723 format: int32
4724
49844725 - `archived_at: string or null`
49854726
49864727 A timestamp in RFC 3339 format
49874728
4729 format: date-time
4730
49884731 - `created_at: string`
49894732
49904733 A timestamp in RFC 3339 format
49914734
4735 format: date-time
4736
49924737 - `description: string or null`
49934738
49944739 Description of what the deployment does.
from line 4746
50014746
50024747 Events sent to each session immediately after creation.
50034748
5004 - `BetaManagedAgentsDeploymentUserMessageEvent object { content, type }`
4749 - `BetaManagedAgentsDeploymentUserMessageEvent object`
50054750
50064751 A user message sent to the session.
50074752
from line 4754
50094754
50104755 Array of content blocks for the user message.
50114756
5012 - `BetaManagedAgentsTextBlock object { text, type }`
4757 - `BetaManagedAgentsTextBlock object`
50134758
50144759 Regular text content.
50154760
from line 4762
50174762
50184763 The text content.
50194764
4765 minLength: 1
4766
50204767 - `type: "text"`
50214768
5022 - `"text"`
5023
5024 - `BetaManagedAgentsImageBlock object { source, type }`
4769 - `BetaManagedAgentsImageBlock object`
50254770
50264771 Image content specified directly as base64 data or as a reference via a URL.
50274772
from line 4774
50294774
50304775 Union type for image source variants.
50314776
5032 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
4777 - `BetaManagedAgentsBase64ImageSource object`
50334778
50344779 Base64-encoded image data.
50354780
from line 4782
50374782
50384783 Base64-encoded image data.
50394784
4785 minLength: 1
4786
50404787 - `media_type: string`
50414788
50424789 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
50434790
4791 minLength: 1
4792
50444793 - `type: "base64"`
50454794
5046 - `"base64"`
5047
5048 - `BetaManagedAgentsURLImageSource object { type, url }`
4795 - `BetaManagedAgentsURLImageSource object`
50494796
50504797 Image referenced by URL.
50514798
50524799 - `type: "url"`
50534800
5054 - `"url"`
5055
50564801 - `url: string`
50574802
50584803 URL of the image to fetch.
50594804
5060 - `BetaManagedAgentsFileImageSource object { file_id, type }`
4805 minLength: 1
4806
4807 - `BetaManagedAgentsFileImageSource object`
50614808
50624809 Image referenced by file ID.
50634810
from line 4812
50654812
50664813 ID of a previously uploaded file.
50674814
4815 minLength: 1
4816
50684817 - `type: "file"`
50694818
5070 - `"file"`
5071
50724819 - `type: "image"`
50734820
5074 - `"image"`
5075
5076 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
4821 - `BetaManagedAgentsDocumentBlock object`
50774822
50784823 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
50794824
from line 4826
50814826
50824827 Union type for document source variants.
50834828
5084 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
4829 - `BetaManagedAgentsBase64DocumentSource object`
50854830
50864831 Base64-encoded document data.
50874832
from line 4834
50894834
50904835 Base64-encoded document data.
50914836
4837 minLength: 1
4838
50924839 - `media_type: string`
50934840
50944841 MIME type of the document (e.g., "application/pdf").
50954842
4843 minLength: 1
4844
50964845 - `type: "base64"`
50974846
5098 - `"base64"`
5099
5100 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
4847 - `BetaManagedAgentsPlainTextDocumentSource object`
51014848
51024849 Plain text document content.
51034850
from line 4852
51054852
51064853 The plain text content.
51074854
4855 minLength: 1
4856
51084857 - `media_type: "text/plain"`
51094858
51104859 MIME type of the text content. Must be "text/plain".
51114860
5112 - `"text/plain"`
5113
51144861 - `type: "text"`
51154862
5116 - `"text"`
5117
5118 - `BetaManagedAgentsURLDocumentSource object { type, url }`
4863 - `BetaManagedAgentsURLDocumentSource object`
51194864
51204865 Document referenced by URL.
51214866
51224867 - `type: "url"`
51234868
5124 - `"url"`
5125
51264869 - `url: string`
51274870
51284871 URL of the document to fetch.
51294872
5130 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
4873 minLength: 1
4874
4875 - `BetaManagedAgentsFileDocumentSource object`
51314876
51324877 Document referenced by file ID.
51334878
from line 4880
51354880
51364881 ID of a previously uploaded file.
51374882
4883 minLength: 1
4884
51384885 - `type: "file"`
51394886
5140 - `"file"`
5141
51424887 - `type: "document"`
51434888
5144 - `"document"`
5145
51464889 - `context: optional string or null`
51474890
51484891 Additional context about the document for the model.
from line 4894
51514894
51524895 The title of the document.
51534896
5154 - `BetaManagedAgentsRedactedBlock object { type }`
4897 - `BetaManagedAgentsRedactedBlock object`
51554898
51564899 Placeholder for content withheld by Anthropic model policy.
51574900
51584901 - `type: "redacted"`
51594902
5160 - `"redacted"`
5161
51624903 - `type: "user.message"`
51634904
5164 - `"user.message"`
5165
5166 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object { description, rubric, type, max_iterations }`
4905 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`
51674906
51684907 An outcome the agent should work toward. The agent begins work on receipt.
51694908
from line 4914
51754914
51764915 Rubric for grading the quality of an outcome.
51774916
5178 - `BetaManagedAgentsFileRubric object { file_id, type }`
4917 - `BetaManagedAgentsFileRubric object`
51794918
51804919 Rubric referenced by a file uploaded via the Files API.
51814920
from line 4924
51854924
51864925 - `type: "file"`
51874926
5188 - `"file"`
5189
5190 - `BetaManagedAgentsTextRubric object { content, type }`
4927 - `BetaManagedAgentsTextRubric object`
51914928
51924929 Rubric content provided inline as text.
51934930
from line 4934
51974934
51984935 - `type: "text"`
51994936
5200 - `"text"`
5201
52024937 - `type: "user.define_outcome"`
52034938
5204 - `"user.define_outcome"`
5205
52064939 - `max_iterations: optional number or null`
52074940
52084941 Eval→revision cycles before giving up. Default 3, max 20.
52094942
5210 - `BetaManagedAgentsDeploymentSystemMessageEvent object { content, type }`
4943 format: int32
4944
4945 - `BetaManagedAgentsDeploymentSystemMessageEvent object`
52114946
52124947 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.
52134948
from line 4954
52194954
52204955 The text content.
52214956
4957 minLength: 1
4958
52224959 - `type: "text"`
52234960
5224 - `"text"`
5225
52264961 - `type: "system.message"`
52274962
5228 - `"system.message"`
5229
52304963 - `metadata: map[string]`
52314964
52324965 Arbitrary key-value metadata. Maximum 16 pairs.
from line 4972
52394972
52404973 Why a deployment is paused. Non-null exactly when `status` is `paused`.
52414974
5242 - `BetaManagedAgentsManualDeploymentPausedReason object { type }`
4975 - `BetaManagedAgentsManualDeploymentPausedReason object`
52434976
52444977 The caller invoked the pause endpoint on the deployment.
52454978
52464979 - `type: "manual"`
52474980
5248 - `"manual"`
5249
5250 - `BetaManagedAgentsErrorDeploymentPausedReason object { error, type }`
4981 - `BetaManagedAgentsErrorDeploymentPausedReason object`
52514982
52524983 A scheduled fire recorded a failed run whose error auto-pauses the deployment.
52534984
from line 4986
52554986
52564987 The error that triggered an auto-pause. Matches the failed run's `error.type`.
52574988
5258 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object { type }`
4989 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object`
52594990
52604991 The deployment's environment was archived.
52614992
52624993 - `type: "environment_archived_error"`
52634994
5264 - `"environment_archived_error"`
5265
5266 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object { type }`
4995 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object`
52674996
52684997 The deployment's agent was archived.
52694998
52704999 - `type: "agent_archived_error"`
52715000
5272 - `"agent_archived_error"`
5273
5274 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object { type }`
5001 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object`
52755002
52765003 The deployment's environment no longer exists.
52775004
52785005 - `type: "environment_not_found_error"`
52795006
5280 - `"environment_not_found_error"`
5281
5282 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object { type }`
5007 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object`
52835008
52845009 A vault referenced by the deployment no longer exists.
52855010
52865011 - `type: "vault_not_found_error"`
52875012
5288 - `"vault_not_found_error"`
5289
5290 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object { type }`
5013 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object`
52915014
52925015 A file resource referenced by the deployment no longer exists.
52935016
52945017 - `type: "file_not_found_error"`
52955018
5296 - `"file_not_found_error"`
5297
5298 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object { type }`
5019 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object`
52995020
53005021 A referenced resource no longer exists and its kind was not reported.
53015022
53025023 - `type: "session_resource_not_found_error"`
53035024
5304 - `"session_resource_not_found_error"`
5305
5306 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object { type }`
5025 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object`
53075026
53085027 The deployment's workspace was archived.
53095028
53105029 - `type: "workspace_archived_error"`
53115030
5312 - `"workspace_archived_error"`
5313
5314 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object { type }`
5031 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object`
53155032
53165033 The deployment's organization is disabled.
53175034
53185035 - `type: "organization_disabled_error"`
53195036
5320 - `"organization_disabled_error"`
5321
5322 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object { type }`
5037 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object`
53235038
53245039 A memory store referenced by the deployment is archived.
53255040
53265041 - `type: "memory_store_archived_error"`
53275042
5328 - `"memory_store_archived_error"`
5329
5330 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object { type }`
5043 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object`
53315044
53325045 A skill referenced by the deployment's agent no longer exists.
53335046
53345047 - `type: "skill_not_found_error"`
53355048
5336 - `"skill_not_found_error"`
5337
5338 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object { type }`
5049 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object`
53395050
53405051 A vault referenced by the deployment is archived.
53415052
53425053 - `type: "vault_archived_error"`
53435054
5344 - `"vault_archived_error"`
5345
5346 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object { type }`
5055 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object`
53475056
53485057 An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.
53495058
53505059 - `type: "unknown_error"`
53515060
5352 - `"unknown_error"`
5353
5354 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object { type }`
5061 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object`
53555062
53565063 The deployment configures resources, but its environment is self-hosted and cannot mount them.
53575064
53585065 - `type: "self_hosted_resources_unsupported_error"`
53595066
5360 - `"self_hosted_resources_unsupported_error"`
5361
5362 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object { type }`
5067 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object`
53635068
53645069 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
53655070
53665071 - `type: "mcp_egress_blocked_error"`
53675072
5368 - `"mcp_egress_blocked_error"`
5369
53705073 - `type: "error"`
53715074
5372 - `"error"`
5373
53745075 - `resources: array of BetaManagedAgentsSessionResourceConfig`
53755076
53765077 Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.
53775078
5378 - `BetaManagedAgentsGitHubRepositoryResourceConfig object { type, url, checkout, mount_path }`
5079 - `BetaManagedAgentsGitHubRepositoryResourceConfig object`
53795080
53805081 A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.
53815082
53825083 - `type: "github_repository"`
53835084
5384 - `"github_repository"`
5385
53865085 - `url: string`
53875086
53885087 Github URL of the repository
from line 5090
53915090
53925091 Branch or commit to check out. Defaults to the repository's default branch.
53935092
5394 - `BetaManagedAgentsBranchCheckout object { name, type }`
5093 - `BetaManagedAgentsBranchCheckout object`
53955094
53965095 - `name: string`
53975096
53985097 Branch name to check out.
53995098
5099 minLength: 1, maxLength: 255
5100
54005101 - `type: "branch"`
54015102
5402 - `"branch"`
5403
5404 - `BetaManagedAgentsCommitCheckout object { sha, type }`
5103 - `BetaManagedAgentsCommitCheckout object`
54055104
54065105 - `sha: string`
54075106
54085107 Full commit SHA to check out.
54095108
5109 minLength: 7, maxLength: 64
5110
54105111 - `type: "commit"`
54115112
5412 - `"commit"`
5413
54145113 - `mount_path: optional string or null`
54155114
54165115 Mount path in the container. Defaults to `/workspace/<repo-name>`.
54175116
5418 - `BetaManagedAgentsFileResourceConfig object { file_id, type, mount_path }`
5117 - `BetaManagedAgentsFileResourceConfig object`
54195118
54205119 A file mounted into each session's container.
54215120
from line 5124
54255124
54265125 - `type: "file"`
54275126
5428 - `"file"`
5429
54305127 - `mount_path: optional string or null`
54315128
54325129 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
54335130
5434 - `BetaManagedAgentsMemoryStoreResourceConfig object { memory_store_id, type, access, instructions }`
5131 - `BetaManagedAgentsMemoryStoreResourceConfig object`
54355132
54365133 A memory store attached to each session created from this deployment.
54375134
from line 5138
54415138
54425139 - `type: "memory_store"`
54435140
5444 - `"memory_store"`
5445
54465141 - `access: optional "read_write" or "read_only" or null`
54475142
54485143 Access mode for an attached memory store.
from line 5158
54635158
54645159 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).
54655160
5161 minLength: 1, maxLength: 256
5162
54665163 - `timezone: string`
54675164
54685165 IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").
54695166
5167 minLength: 1
5168
54705169 - `type: "cron"`
54715170
5472 - `"cron"`
5473
54745171 - `last_run_at: optional string or null`
54755172
54765173 A timestamp in RFC 3339 format
54775174
5175 format: date-time
5176
54785177 - `upcoming_runs_at: optional array of string`
54795178
54805179 Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.
from line 5188
54895188
54905189 - `type: "deployment"`
54915190
5492 - `"deployment"`
5493
54945191 - `updated_at: string`
54955192
54965193 A timestamp in RFC 3339 format
54975194
5195 format: date-time
5196
54985197 - `vault_ids: array of string`
54995198
55005199 Vault IDs supplying stored credentials for sessions created from this deployment.
from line 5214
55155214
55165215 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.
55175216
5518 - `"USD"`
5519
55205217 - `type: "limit"`
55215218
5522 - `"limit"`
5523
55245219### Example
55255220
5526```http
5221```bash
55275222curl https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/pause \
55285223 -X POST \
55295224 -H 'anthropic-version: 2023-06-01' \
from line 5226
55315226 -H "X-Api-Key: $ANTHROPIC_API_KEY"
55325227```
55335228
5534#### Response
5229#### Response (200)
55355230
55365231```json
55375232{
from line 5295
56005295
56015296## Unpause Deployment
56025297
5603**post** `/v1/deployments/{deployment_id}/unpause`
5298**POST** `/v1/deployments/{deployment_id}/unpause`
56045299
56055300Unpause Deployment
56065301
5607### Path Parameters
5302### Path parameters
56085303
56095304- `deployment_id: string`
56105305
5611### Header Parameters
5306### Headers
56125307
56135308- `"anthropic-beta": optional array of AnthropicBeta`
56145309
from line 5383
56885383
56895384### Returns
56905385
5691- `BetaManagedAgentsDeployment object { id, agent, archived_at, 14 more }`
5386- `BetaManagedAgentsDeployment object`
56925387
56935388 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.
56945389
from line 5399
57045399
57055400 - `type: "agent"`
57065401
5707 - `"agent"`
5708
57095402 - `version: number`
57105403
5404 format: int32
5405
57115406 - `archived_at: string or null`
57125407
57135408 A timestamp in RFC 3339 format
57145409
5410 format: date-time
5411
57155412 - `created_at: string`
57165413
57175414 A timestamp in RFC 3339 format
57185415
5416 format: date-time
5417
57195418 - `description: string or null`
57205419
57215420 Description of what the deployment does.
from line 5427
57285427
57295428 Events sent to each session immediately after creation.
57305429
5731 - `BetaManagedAgentsDeploymentUserMessageEvent object { content, type }`
5430 - `BetaManagedAgentsDeploymentUserMessageEvent object`
57325431
57335432 A user message sent to the session.
57345433
from line 5435
57365435
57375436 Array of content blocks for the user message.
57385437
5739 - `BetaManagedAgentsTextBlock object { text, type }`
5438 - `BetaManagedAgentsTextBlock object`
57405439
57415440 Regular text content.
57425441
from line 5443
57445443
57455444 The text content.
57465445
5446 minLength: 1
5447
57475448 - `type: "text"`
57485449
5749 - `"text"`
5750
5751 - `BetaManagedAgentsImageBlock object { source, type }`
5450 - `BetaManagedAgentsImageBlock object`
57525451
57535452 Image content specified directly as base64 data or as a reference via a URL.
57545453
from line 5455
57565455
57575456 Union type for image source variants.
57585457
5759 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
5458 - `BetaManagedAgentsBase64ImageSource object`
57605459
57615460 Base64-encoded image data.
57625461
from line 5463
57645463
57655464 Base64-encoded image data.
57665465
5466 minLength: 1
5467
57675468 - `media_type: string`
57685469
57695470 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
57705471
5472 minLength: 1
5473
57715474 - `type: "base64"`
57725475
5773 - `"base64"`
5774
5775 - `BetaManagedAgentsURLImageSource object { type, url }`
5476 - `BetaManagedAgentsURLImageSource object`
57765477
57775478 Image referenced by URL.
57785479
57795480 - `type: "url"`
57805481
5781 - `"url"`
5782
57835482 - `url: string`
57845483
57855484 URL of the image to fetch.
57865485
5787 - `BetaManagedAgentsFileImageSource object { file_id, type }`
5486 minLength: 1
5487
5488 - `BetaManagedAgentsFileImageSource object`
57885489
57895490 Image referenced by file ID.
57905491
from line 5493
57925493
57935494 ID of a previously uploaded file.
57945495
5496 minLength: 1
5497
57955498 - `type: "file"`
57965499
5797 - `"file"`
5798
57995500 - `type: "image"`
58005501
5801 - `"image"`
5802
5803 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
5502 - `BetaManagedAgentsDocumentBlock object`
58045503
58055504 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
58065505
from line 5507
58085507
58095508 Union type for document source variants.
58105509
5811 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
5510 - `BetaManagedAgentsBase64DocumentSource object`
58125511
58135512 Base64-encoded document data.
58145513
from line 5515
58165515
58175516 Base64-encoded document data.
58185517
5518 minLength: 1
5519
58195520 - `media_type: string`
58205521
58215522 MIME type of the document (e.g., "application/pdf").
58225523
5524 minLength: 1
5525
58235526 - `type: "base64"`
58245527
5825 - `"base64"`
5826
5827 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
5528 - `BetaManagedAgentsPlainTextDocumentSource object`
58285529
58295530 Plain text document content.
58305531
from line 5533
58325533
58335534 The plain text content.
58345535
5536 minLength: 1
5537
58355538 - `media_type: "text/plain"`
58365539
58375540 MIME type of the text content. Must be "text/plain".
58385541
5839 - `"text/plain"`
5840
58415542 - `type: "text"`
58425543
5843 - `"text"`
5844
5845 - `BetaManagedAgentsURLDocumentSource object { type, url }`
5544 - `BetaManagedAgentsURLDocumentSource object`
58465545
58475546 Document referenced by URL.
58485547
58495548 - `type: "url"`
58505549
5851 - `"url"`
5852
58535550 - `url: string`
58545551
58555552 URL of the document to fetch.
58565553
5857 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
5554 minLength: 1
5555
5556 - `BetaManagedAgentsFileDocumentSource object`
58585557
58595558 Document referenced by file ID.
58605559
from line 5561
58625561
58635562 ID of a previously uploaded file.
58645563
5564 minLength: 1
5565
58655566 - `type: "file"`
58665567
5867 - `"file"`
5868
58695568 - `type: "document"`
58705569
5871 - `"document"`
5872
58735570 - `context: optional string or null`
58745571
58755572 Additional context about the document for the model.
from line 5575
58785575
58795576 The title of the document.
58805577
5881 - `BetaManagedAgentsRedactedBlock object { type }`
5578 - `BetaManagedAgentsRedactedBlock object`
58825579
58835580 Placeholder for content withheld by Anthropic model policy.
58845581
58855582 - `type: "redacted"`
58865583
5887 - `"redacted"`
5888
58895584 - `type: "user.message"`
58905585
5891 - `"user.message"`
5892
5893 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object { description, rubric, type, max_iterations }`
5586 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`
58945587
58955588 An outcome the agent should work toward. The agent begins work on receipt.
58965589
from line 5595
59025595
59035596 Rubric for grading the quality of an outcome.
59045597
5905 - `BetaManagedAgentsFileRubric object { file_id, type }`
5598 - `BetaManagedAgentsFileRubric object`
59065599
59075600 Rubric referenced by a file uploaded via the Files API.
59085601
from line 5605
59125605
59135606 - `type: "file"`
59145607
5915 - `"file"`
5916
5917 - `BetaManagedAgentsTextRubric object { content, type }`
5608 - `BetaManagedAgentsTextRubric object`
59185609
59195610 Rubric content provided inline as text.
59205611
from line 5615
59245615
59255616 - `type: "text"`
59265617
5927 - `"text"`
5928
59295618 - `type: "user.define_outcome"`
59305619
5931 - `"user.define_outcome"`
5932
59335620 - `max_iterations: optional number or null`
59345621
59355622 Eval→revision cycles before giving up. Default 3, max 20.
59365623
5937 - `BetaManagedAgentsDeploymentSystemMessageEvent object { content, type }`
5624 format: int32
5625
5626 - `BetaManagedAgentsDeploymentSystemMessageEvent object`
59385627
59395628 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.
59405629
from line 5635
59465635
59475636 The text content.
59485637
5638 minLength: 1
5639
59495640 - `type: "text"`
59505641
5951 - `"text"`
5952
59535642 - `type: "system.message"`
59545643
5955 - `"system.message"`
5956
59575644 - `metadata: map[string]`
59585645
59595646 Arbitrary key-value metadata. Maximum 16 pairs.
from line 5653
59665653
59675654 Why a deployment is paused. Non-null exactly when `status` is `paused`.
59685655
5969 - `BetaManagedAgentsManualDeploymentPausedReason object { type }`
5656 - `BetaManagedAgentsManualDeploymentPausedReason object`
59705657
59715658 The caller invoked the pause endpoint on the deployment.
59725659
59735660 - `type: "manual"`
59745661
5975 - `"manual"`
5976
5977 - `BetaManagedAgentsErrorDeploymentPausedReason object { error, type }`
5662 - `BetaManagedAgentsErrorDeploymentPausedReason object`
59785663
59795664 A scheduled fire recorded a failed run whose error auto-pauses the deployment.
59805665
from line 5667
59825667
59835668 The error that triggered an auto-pause. Matches the failed run's `error.type`.
59845669
5985 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object { type }`
5670 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object`
59865671
59875672 The deployment's environment was archived.
59885673
59895674 - `type: "environment_archived_error"`
59905675
5991 - `"environment_archived_error"`
5992
5993 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object { type }`
5676 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object`
59945677
59955678 The deployment's agent was archived.
59965679
59975680 - `type: "agent_archived_error"`
59985681
5999 - `"agent_archived_error"`
6000
6001 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object { type }`
5682 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object`
60025683
60035684 The deployment's environment no longer exists.
60045685
60055686 - `type: "environment_not_found_error"`
60065687
6007 - `"environment_not_found_error"`
6008
6009 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object { type }`
5688 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object`
60105689
60115690 A vault referenced by the deployment no longer exists.
60125691
60135692 - `type: "vault_not_found_error"`
60145693
6015 - `"vault_not_found_error"`
6016
6017 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object { type }`
5694 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object`
60185695
60195696 A file resource referenced by the deployment no longer exists.
60205697
60215698 - `type: "file_not_found_error"`
60225699
6023 - `"file_not_found_error"`
6024
6025 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object { type }`
5700 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object`
60265701
60275702 A referenced resource no longer exists and its kind was not reported.
60285703
60295704 - `type: "session_resource_not_found_error"`
60305705
6031 - `"session_resource_not_found_error"`
6032
6033 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object { type }`
5706 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object`
60345707
60355708 The deployment's workspace was archived.
60365709
60375710 - `type: "workspace_archived_error"`
60385711
6039 - `"workspace_archived_error"`
6040
6041 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object { type }`
5712 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object`
60425713
60435714 The deployment's organization is disabled.
60445715
60455716 - `type: "organization_disabled_error"`
60465717
6047 - `"organization_disabled_error"`
6048
6049 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object { type }`
5718 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object`
60505719
60515720 A memory store referenced by the deployment is archived.
60525721
60535722 - `type: "memory_store_archived_error"`
60545723
6055 - `"memory_store_archived_error"`
6056
6057 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object { type }`
5724 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object`
60585725
60595726 A skill referenced by the deployment's agent no longer exists.
60605727
60615728 - `type: "skill_not_found_error"`
60625729
6063 - `"skill_not_found_error"`
6064
6065 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object { type }`
5730 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object`
60665731
60675732 A vault referenced by the deployment is archived.
60685733
60695734 - `type: "vault_archived_error"`
60705735
6071 - `"vault_archived_error"`
6072
6073 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object { type }`
5736 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object`
60745737
60755738 An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.
60765739
60775740 - `type: "unknown_error"`
60785741
6079 - `"unknown_error"`
6080
6081 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object { type }`
5742 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object`
60825743
60835744 The deployment configures resources, but its environment is self-hosted and cannot mount them.
60845745
60855746 - `type: "self_hosted_resources_unsupported_error"`
60865747
6087 - `"self_hosted_resources_unsupported_error"`
6088
6089 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object { type }`
5748 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object`
60905749
60915750 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
60925751
60935752 - `type: "mcp_egress_blocked_error"`
60945753
6095 - `"mcp_egress_blocked_error"`
6096
60975754 - `type: "error"`
60985755
6099 - `"error"`
6100
61015756 - `resources: array of BetaManagedAgentsSessionResourceConfig`
61025757
61035758 Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.
61045759
6105 - `BetaManagedAgentsGitHubRepositoryResourceConfig object { type, url, checkout, mount_path }`
5760 - `BetaManagedAgentsGitHubRepositoryResourceConfig object`
61065761
61075762 A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.
61085763
61095764 - `type: "github_repository"`
61105765
6111 - `"github_repository"`
6112
61135766 - `url: string`
61145767
61155768 Github URL of the repository
from line 5771
61185771
61195772 Branch or commit to check out. Defaults to the repository's default branch.
61205773
6121 - `BetaManagedAgentsBranchCheckout object { name, type }`
5774 - `BetaManagedAgentsBranchCheckout object`
61225775
61235776 - `name: string`
61245777
61255778 Branch name to check out.
61265779
5780 minLength: 1, maxLength: 255
5781
61275782 - `type: "branch"`
61285783
6129 - `"branch"`
6130
6131 - `BetaManagedAgentsCommitCheckout object { sha, type }`
5784 - `BetaManagedAgentsCommitCheckout object`
61325785
61335786 - `sha: string`
61345787
61355788 Full commit SHA to check out.
61365789
5790 minLength: 7, maxLength: 64
5791
61375792 - `type: "commit"`
61385793
6139 - `"commit"`
6140
61415794 - `mount_path: optional string or null`
61425795
61435796 Mount path in the container. Defaults to `/workspace/<repo-name>`.
61445797
6145 - `BetaManagedAgentsFileResourceConfig object { file_id, type, mount_path }`
5798 - `BetaManagedAgentsFileResourceConfig object`
61465799
61475800 A file mounted into each session's container.
61485801
from line 5805
61525805
61535806 - `type: "file"`
61545807
6155 - `"file"`
6156
61575808 - `mount_path: optional string or null`
61585809
61595810 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
61605811
6161 - `BetaManagedAgentsMemoryStoreResourceConfig object { memory_store_id, type, access, instructions }`
5812 - `BetaManagedAgentsMemoryStoreResourceConfig object`
61625813
61635814 A memory store attached to each session created from this deployment.
61645815
from line 5819
61685819
61695820 - `type: "memory_store"`
61705821
6171 - `"memory_store"`
6172
61735822 - `access: optional "read_write" or "read_only" or null`
61745823
61755824 Access mode for an attached memory store.
from line 5839
61905839
61915840 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).
61925841
5842 minLength: 1, maxLength: 256
5843
61935844 - `timezone: string`
61945845
61955846 IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").
61965847
5848 minLength: 1
5849
61975850 - `type: "cron"`
61985851
6199 - `"cron"`
6200
62015852 - `last_run_at: optional string or null`
62025853
62035854 A timestamp in RFC 3339 format
62045855
5856 format: date-time
5857
62055858 - `upcoming_runs_at: optional array of string`
62065859
62075860 Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.
from line 5869
62165869
62175870 - `type: "deployment"`
62185871
6219 - `"deployment"`
6220
62215872 - `updated_at: string`
62225873
62235874 A timestamp in RFC 3339 format
62245875
5876 format: date-time
5877
62255878 - `vault_ids: array of string`
62265879
62275880 Vault IDs supplying stored credentials for sessions created from this deployment.
from line 5895
62425895
62435896 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.
62445897
6245 - `"USD"`
6246
62475898 - `type: "limit"`
62485899
6249 - `"limit"`
6250
62515900### Example
62525901
6253```http
5902```bash
62545903curl https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/unpause \
62555904 -X POST \
62565905 -H 'anthropic-version: 2023-06-01' \
from line 5907
62585907 -H "X-Api-Key: $ANTHROPIC_API_KEY"
62595908```
62605909
6261#### Response
5910#### Response (200)
62625911
62635912```json
62645913{
from line 5974
63255974}
63265975```
63275976
6328## Domain Types
5977## Domain types
63295978
63305979### Beta Managed Agents Agent Archived Deployment Paused Reason Error
63315980
6332- `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object { type }`
5981- `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object`
63335982
63345983 The deployment's agent was archived.
63355984
63365985 - `type: "agent_archived_error"`
63375986
6338 - `"agent_archived_error"`
6339
63405987### Beta Managed Agents Cron Schedule
63415988
6342- `BetaManagedAgentsCronSchedule object { expression, timezone, type, 2 more }`
5989- `BetaManagedAgentsCronSchedule object`
63435990
63445991 5-field POSIX cron schedule with computed runtime timestamps.
63455992
from line 5994
63475994
63485995 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).
63495996
5997 minLength: 1, maxLength: 256
5998
63505999 - `timezone: string`
63516000
63526001 IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").
63536002
6003 minLength: 1
6004
63546005 - `type: "cron"`
63556006
6356 - `"cron"`
6357
63586007 - `last_run_at: optional string or null`
63596008
63606009 A timestamp in RFC 3339 format
63616010
6011 format: date-time
6012
63626013 - `upcoming_runs_at: optional array of string`
63636014
63646015 Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.
63656016
63666017### Beta Managed Agents Cron Schedule Params
63676018
6368- `BetaManagedAgentsCronScheduleParams object { expression, timezone, type }`
6019- `BetaManagedAgentsCronScheduleParams object`
63696020
63706021 5-field POSIX cron schedule. Literal wall-clock matching in the configured timezone.
63716022
from line 6024
63736024
63746025 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).
63756026
6027 minLength: 1, maxLength: 256
6028
63766029 - `timezone: string`
63776030
63786031 Required. IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). Validated against the IANA timezone database.
63796032
6033 minLength: 1
6034
63806035 - `type: "cron"`
63816036
6382 - `"cron"`
6383
63846037### Beta Managed Agents Deployment
63856038
6386- `BetaManagedAgentsDeployment object { id, agent, archived_at, 14 more }`
6039- `BetaManagedAgentsDeployment object`
63876040
63886041 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.
63896042
from line 6052
63996052
64006053 - `type: "agent"`
64016054
6402 - `"agent"`
6403
64046055 - `version: number`
64056056
6057 format: int32
6058
64066059 - `archived_at: string or null`
64076060
64086061 A timestamp in RFC 3339 format
64096062
6063 format: date-time
6064
64106065 - `created_at: string`
64116066
64126067 A timestamp in RFC 3339 format
64136068
6069 format: date-time
6070
64146071 - `description: string or null`
64156072
64166073 Description of what the deployment does.
from line 6080
64236080
64246081 Events sent to each session immediately after creation.
64256082
6426 - `BetaManagedAgentsDeploymentUserMessageEvent object { content, type }`
6083 - `BetaManagedAgentsDeploymentUserMessageEvent object`
64276084
64286085 A user message sent to the session.
64296086
from line 6088
64316088
64326089 Array of content blocks for the user message.
64336090
6434 - `BetaManagedAgentsTextBlock object { text, type }`
6091 - `BetaManagedAgentsTextBlock object`
64356092
64366093 Regular text content.
64376094
from line 6096
64396096
64406097 The text content.
64416098
6099 minLength: 1
6100
64426101 - `type: "text"`
64436102
6444 - `"text"`
6445
6446 - `BetaManagedAgentsImageBlock object { source, type }`
6103 - `BetaManagedAgentsImageBlock object`
64476104
64486105 Image content specified directly as base64 data or as a reference via a URL.
64496106
from line 6108
64516108
64526109 Union type for image source variants.
64536110
6454 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
6111 - `BetaManagedAgentsBase64ImageSource object`
64556112
64566113 Base64-encoded image data.
64576114
from line 6116
64596116
64606117 Base64-encoded image data.
64616118
6119 minLength: 1
6120
64626121 - `media_type: string`
64636122
64646123 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
64656124
6125 minLength: 1
6126
64666127 - `type: "base64"`
64676128
6468 - `"base64"`
6469
6470 - `BetaManagedAgentsURLImageSource object { type, url }`
6129 - `BetaManagedAgentsURLImageSource object`
64716130
64726131 Image referenced by URL.
64736132
64746133 - `type: "url"`
64756134
6476 - `"url"`
6477
64786135 - `url: string`
64796136
64806137 URL of the image to fetch.
64816138
6482 - `BetaManagedAgentsFileImageSource object { file_id, type }`
6139 minLength: 1
6140
6141 - `BetaManagedAgentsFileImageSource object`
64836142
64846143 Image referenced by file ID.
64856144
from line 6146
64876146
64886147 ID of a previously uploaded file.
64896148
6149 minLength: 1
6150
64906151 - `type: "file"`
64916152
6492 - `"file"`
6493
64946153 - `type: "image"`
64956154
6496 - `"image"`
6497
6498 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
6155 - `BetaManagedAgentsDocumentBlock object`
64996156
65006157 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
65016158
from line 6160
65036160
65046161 Union type for document source variants.
65056162
6506 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
6163 - `BetaManagedAgentsBase64DocumentSource object`
65076164
65086165 Base64-encoded document data.
65096166
from line 6168
65116168
65126169 Base64-encoded document data.
65136170
6171 minLength: 1
6172
65146173 - `media_type: string`
65156174
65166175 MIME type of the document (e.g., "application/pdf").
65176176
6177 minLength: 1
6178
65186179 - `type: "base64"`
65196180
6520 - `"base64"`
6521
6522 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
6181 - `BetaManagedAgentsPlainTextDocumentSource object`
65236182
65246183 Plain text document content.
65256184
from line 6186
65276186
65286187 The plain text content.
65296188
6189 minLength: 1
6190
65306191 - `media_type: "text/plain"`
65316192
65326193 MIME type of the text content. Must be "text/plain".
65336194
6534 - `"text/plain"`
6535
65366195 - `type: "text"`
65376196
6538 - `"text"`
6539
6540 - `BetaManagedAgentsURLDocumentSource object { type, url }`
6197 - `BetaManagedAgentsURLDocumentSource object`
65416198
65426199 Document referenced by URL.
65436200
65446201 - `type: "url"`
65456202
6546 - `"url"`
6547
65486203 - `url: string`
65496204
65506205 URL of the document to fetch.
65516206
6552 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
6207 minLength: 1
6208
6209 - `BetaManagedAgentsFileDocumentSource object`
65536210
65546211 Document referenced by file ID.
65556212
from line 6214
65576214
65586215 ID of a previously uploaded file.
65596216
6217 minLength: 1
6218
65606219 - `type: "file"`
65616220
6562 - `"file"`
6563
65646221 - `type: "document"`
65656222
6566 - `"document"`
6567
65686223 - `context: optional string or null`
65696224
65706225 Additional context about the document for the model.
from line 6228
65736228
65746229 The title of the document.
65756230
6576 - `BetaManagedAgentsRedactedBlock object { type }`
6231 - `BetaManagedAgentsRedactedBlock object`
65776232
65786233 Placeholder for content withheld by Anthropic model policy.
65796234
65806235 - `type: "redacted"`
65816236
6582 - `"redacted"`
6583
65846237 - `type: "user.message"`
65856238
6586 - `"user.message"`
6587
6588 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object { description, rubric, type, max_iterations }`
6239 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`
65896240
65906241 An outcome the agent should work toward. The agent begins work on receipt.
65916242
from line 6248
65976248
65986249 Rubric for grading the quality of an outcome.
65996250
6600 - `BetaManagedAgentsFileRubric object { file_id, type }`
6251 - `BetaManagedAgentsFileRubric object`
66016252
66026253 Rubric referenced by a file uploaded via the Files API.
66036254
from line 6258
66076258
66086259 - `type: "file"`
66096260
6610 - `"file"`
6611
6612 - `BetaManagedAgentsTextRubric object { content, type }`
6261 - `BetaManagedAgentsTextRubric object`
66136262
66146263 Rubric content provided inline as text.
66156264
from line 6268
66196268
66206269 - `type: "text"`
66216270
6622 - `"text"`
6623
66246271 - `type: "user.define_outcome"`
66256272
6626 - `"user.define_outcome"`
6627
66286273 - `max_iterations: optional number or null`
66296274
66306275 Eval→revision cycles before giving up. Default 3, max 20.
66316276
6632 - `BetaManagedAgentsDeploymentSystemMessageEvent object { content, type }`
6277 format: int32
6278
6279 - `BetaManagedAgentsDeploymentSystemMessageEvent object`
66336280
66346281 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.
66356282
from line 6288
66416288
66426289 The text content.
66436290
6291 minLength: 1
6292
66446293 - `type: "text"`
66456294
6646 - `"text"`
6647
66486295 - `type: "system.message"`
66496296
6650 - `"system.message"`
6651
66526297 - `metadata: map[string]`
66536298
66546299 Arbitrary key-value metadata. Maximum 16 pairs.
from line 6306
66616306
66626307 Why a deployment is paused. Non-null exactly when `status` is `paused`.
66636308
6664 - `BetaManagedAgentsManualDeploymentPausedReason object { type }`
6309 - `BetaManagedAgentsManualDeploymentPausedReason object`
66656310
66666311 The caller invoked the pause endpoint on the deployment.
66676312
66686313 - `type: "manual"`
66696314
6670 - `"manual"`
6671
6672 - `BetaManagedAgentsErrorDeploymentPausedReason object { error, type }`
6315 - `BetaManagedAgentsErrorDeploymentPausedReason object`
66736316
66746317 A scheduled fire recorded a failed run whose error auto-pauses the deployment.
66756318
from line 6320
66776320
66786321 The error that triggered an auto-pause. Matches the failed run's `error.type`.
66796322
6680 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object { type }`
6323 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object`
66816324
66826325 The deployment's environment was archived.
66836326
66846327 - `type: "environment_archived_error"`
66856328
6686 - `"environment_archived_error"`
6687
6688 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object { type }`
6329 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object`
66896330
66906331 The deployment's agent was archived.
66916332
66926333 - `type: "agent_archived_error"`
66936334
6694 - `"agent_archived_error"`
6695
6696 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object { type }`
6335 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object`
66976336
66986337 The deployment's environment no longer exists.
66996338
67006339 - `type: "environment_not_found_error"`
67016340
6702 - `"environment_not_found_error"`
6703
6704 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object { type }`
6341 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object`
67056342
67066343 A vault referenced by the deployment no longer exists.
67076344
67086345 - `type: "vault_not_found_error"`
67096346
6710 - `"vault_not_found_error"`
6711
6712 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object { type }`
6347 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object`
67136348
67146349 A file resource referenced by the deployment no longer exists.
67156350
67166351 - `type: "file_not_found_error"`
67176352
6718 - `"file_not_found_error"`
6719
6720 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object { type }`
6353 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object`
67216354
67226355 A referenced resource no longer exists and its kind was not reported.
67236356
67246357 - `type: "session_resource_not_found_error"`
67256358
6726 - `"session_resource_not_found_error"`
6727
6728 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object { type }`
6359 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object`
67296360
67306361 The deployment's workspace was archived.
67316362
67326363 - `type: "workspace_archived_error"`
67336364
6734 - `"workspace_archived_error"`
6735
6736 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object { type }`
6365 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object`
67376366
67386367 The deployment's organization is disabled.
67396368
67406369 - `type: "organization_disabled_error"`
67416370
6742 - `"organization_disabled_error"`
6743
6744 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object { type }`
6371 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object`
67456372
67466373 A memory store referenced by the deployment is archived.
67476374
67486375 - `type: "memory_store_archived_error"`
67496376
6750 - `"memory_store_archived_error"`
6751
6752 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object { type }`
6377 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object`
67536378
67546379 A skill referenced by the deployment's agent no longer exists.
67556380
67566381 - `type: "skill_not_found_error"`
67576382
6758 - `"skill_not_found_error"`
6759
6760 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object { type }`
6383 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object`
67616384
67626385 A vault referenced by the deployment is archived.
67636386
67646387 - `type: "vault_archived_error"`
67656388
6766 - `"vault_archived_error"`
6767
6768 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object { type }`
6389 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object`
67696390
67706391 An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.
67716392
67726393 - `type: "unknown_error"`
67736394
6774 - `"unknown_error"`
6775
6776 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object { type }`
6395 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object`
67776396
67786397 The deployment configures resources, but its environment is self-hosted and cannot mount them.
67796398
67806399 - `type: "self_hosted_resources_unsupported_error"`
67816400
6782 - `"self_hosted_resources_unsupported_error"`
6783
6784 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object { type }`
6401 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object`
67856402
67866403 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
67876404
67886405 - `type: "mcp_egress_blocked_error"`
67896406
6790 - `"mcp_egress_blocked_error"`
6791
67926407 - `type: "error"`
67936408
6794 - `"error"`
6795
67966409 - `resources: array of BetaManagedAgentsSessionResourceConfig`
67976410
67986411 Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.
67996412
6800 - `BetaManagedAgentsGitHubRepositoryResourceConfig object { type, url, checkout, mount_path }`
6413 - `BetaManagedAgentsGitHubRepositoryResourceConfig object`
68016414
68026415 A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.
68036416
68046417 - `type: "github_repository"`
68056418
6806 - `"github_repository"`
6807
68086419 - `url: string`
68096420
68106421 Github URL of the repository
from line 6424
68136424
68146425 Branch or commit to check out. Defaults to the repository's default branch.
68156426
6816 - `BetaManagedAgentsBranchCheckout object { name, type }`
6427 - `BetaManagedAgentsBranchCheckout object`
68176428
68186429 - `name: string`
68196430
68206431 Branch name to check out.
68216432
6433 minLength: 1, maxLength: 255
6434
68226435 - `type: "branch"`
68236436
6824 - `"branch"`
6825
6826 - `BetaManagedAgentsCommitCheckout object { sha, type }`
6437 - `BetaManagedAgentsCommitCheckout object`
68276438
68286439 - `sha: string`
68296440
68306441 Full commit SHA to check out.
68316442
6443 minLength: 7, maxLength: 64
6444
68326445 - `type: "commit"`
68336446
6834 - `"commit"`
6835
68366447 - `mount_path: optional string or null`
68376448
68386449 Mount path in the container. Defaults to `/workspace/<repo-name>`.
68396450
6840 - `BetaManagedAgentsFileResourceConfig object { file_id, type, mount_path }`
6451 - `BetaManagedAgentsFileResourceConfig object`
68416452
68426453 A file mounted into each session's container.
68436454
from line 6458
68476458
68486459 - `type: "file"`
68496460
6850 - `"file"`
6851
68526461 - `mount_path: optional string or null`
68536462
68546463 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
68556464
6856 - `BetaManagedAgentsMemoryStoreResourceConfig object { memory_store_id, type, access, instructions }`
6465 - `BetaManagedAgentsMemoryStoreResourceConfig object`
68576466
68586467 A memory store attached to each session created from this deployment.
68596468
from line 6472
68636472
68646473 - `type: "memory_store"`
68656474
6866 - `"memory_store"`
6867
68686475 - `access: optional "read_write" or "read_only" or null`
68696476
68706477 Access mode for an attached memory store.
from line 6492
68856492
68866493 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).
68876494
6495 minLength: 1, maxLength: 256
6496
68886497 - `timezone: string`
68896498
68906499 IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").
68916500
6501 minLength: 1
6502
68926503 - `type: "cron"`
68936504
6894 - `"cron"`
6895
68966505 - `last_run_at: optional string or null`
68976506
68986507 A timestamp in RFC 3339 format
68996508
6509 format: date-time
6510
69006511 - `upcoming_runs_at: optional array of string`
69016512
69026513 Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.
from line 6522
69116522
69126523 - `type: "deployment"`
69136524
6914 - `"deployment"`
6915
69166525 - `updated_at: string`
69176526
69186527 A timestamp in RFC 3339 format
69196528
6529 format: date-time
6530
69206531 - `vault_ids: array of string`
69216532
69226533 Vault IDs supplying stored credentials for sessions created from this deployment.
from line 6548
69376548
69386549 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.
69396550
6940 - `"USD"`
6941
69426551 - `type: "limit"`
69436552
6944 - `"limit"`
6945
69466553### Beta Managed Agents Deployment Initial Event
69476554
69486555- `BetaManagedAgentsDeploymentInitialEvent = BetaManagedAgentsDeploymentUserMessageEvent or BetaManagedAgentsDeploymentUserDefineOutcomeEvent or BetaManagedAgentsDeploymentSystemMessageEvent`
69496556
69506557 An event sent to a session immediately after it is created. Supports `user.message`, `user.define_outcome`, and `system.message`.
69516558
6952 - `BetaManagedAgentsDeploymentUserMessageEvent object { content, type }`
6559 - `BetaManagedAgentsDeploymentUserMessageEvent object`
69536560
69546561 A user message sent to the session.
69556562
from line 6564
69576564
69586565 Array of content blocks for the user message.
69596566
6960 - `BetaManagedAgentsTextBlock object { text, type }`
6567 - `BetaManagedAgentsTextBlock object`
69616568
69626569 Regular text content.
69636570
from line 6572
69656572
69666573 The text content.
69676574
6575 minLength: 1
6576
69686577 - `type: "text"`
69696578
6970 - `"text"`
6971
6972 - `BetaManagedAgentsImageBlock object { source, type }`
6579 - `BetaManagedAgentsImageBlock object`
69736580
69746581 Image content specified directly as base64 data or as a reference via a URL.
69756582
from line 6584
69776584
69786585 Union type for image source variants.
69796586
6980 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
6587 - `BetaManagedAgentsBase64ImageSource object`
69816588
69826589 Base64-encoded image data.
69836590
from line 6592
69856592
69866593 Base64-encoded image data.
69876594
6595 minLength: 1
6596
69886597 - `media_type: string`
69896598
69906599 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
69916600
6601 minLength: 1
6602
69926603 - `type: "base64"`
69936604
6994 - `"base64"`
6995
6996 - `BetaManagedAgentsURLImageSource object { type, url }`
6605 - `BetaManagedAgentsURLImageSource object`
69976606
69986607 Image referenced by URL.
69996608
70006609 - `type: "url"`
70016610
7002 - `"url"`
7003
70046611 - `url: string`
70056612
70066613 URL of the image to fetch.
70076614
7008 - `BetaManagedAgentsFileImageSource object { file_id, type }`
6615 minLength: 1
6616
6617 - `BetaManagedAgentsFileImageSource object`
70096618
70106619 Image referenced by file ID.
70116620
from line 6622
70136622
70146623 ID of a previously uploaded file.
70156624
6625 minLength: 1
6626
70166627 - `type: "file"`
70176628
7018 - `"file"`
7019
70206629 - `type: "image"`
70216630
7022 - `"image"`
7023
7024 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
6631 - `BetaManagedAgentsDocumentBlock object`
70256632
70266633 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
70276634
from line 6636
70296636
70306637 Union type for document source variants.
70316638
7032 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
6639 - `BetaManagedAgentsBase64DocumentSource object`
70336640
70346641 Base64-encoded document data.
70356642
from line 6644
70376644
70386645 Base64-encoded document data.
70396646
6647 minLength: 1
6648
70406649 - `media_type: string`
70416650
70426651 MIME type of the document (e.g., "application/pdf").
70436652
6653 minLength: 1
6654
70446655 - `type: "base64"`
70456656
7046 - `"base64"`
7047
7048 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
6657 - `BetaManagedAgentsPlainTextDocumentSource object`
70496658
70506659 Plain text document content.
70516660
from line 6662
70536662
70546663 The plain text content.
70556664
6665 minLength: 1
6666
70566667 - `media_type: "text/plain"`
70576668
70586669 MIME type of the text content. Must be "text/plain".
70596670
7060 - `"text/plain"`
7061
70626671 - `type: "text"`
70636672
7064 - `"text"`
7065
7066 - `BetaManagedAgentsURLDocumentSource object { type, url }`
6673 - `BetaManagedAgentsURLDocumentSource object`
70676674
70686675 Document referenced by URL.
70696676
70706677 - `type: "url"`
70716678
7072 - `"url"`
7073
70746679 - `url: string`
70756680
70766681 URL of the document to fetch.
70776682
7078 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
6683 minLength: 1
6684
6685 - `BetaManagedAgentsFileDocumentSource object`
70796686
70806687 Document referenced by file ID.
70816688
from line 6690
70836690
70846691 ID of a previously uploaded file.
70856692
6693 minLength: 1
6694
70866695 - `type: "file"`
70876696
7088 - `"file"`
7089
70906697 - `type: "document"`
70916698
7092 - `"document"`
7093
70946699 - `context: optional string or null`
70956700
70966701 Additional context about the document for the model.
from line 6704
70996704
71006705 The title of the document.
71016706
7102 - `BetaManagedAgentsRedactedBlock object { type }`
6707 - `BetaManagedAgentsRedactedBlock object`
71036708
71046709 Placeholder for content withheld by Anthropic model policy.
71056710
71066711 - `type: "redacted"`
71076712
7108 - `"redacted"`
7109
71106713 - `type: "user.message"`
71116714
7112 - `"user.message"`
7113
7114 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object { description, rubric, type, max_iterations }`
6715 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`
71156716
71166717 An outcome the agent should work toward. The agent begins work on receipt.
71176718
from line 6724
71236724
71246725 Rubric for grading the quality of an outcome.
71256726
7126 - `BetaManagedAgentsFileRubric object { file_id, type }`
6727 - `BetaManagedAgentsFileRubric object`
71276728
71286729 Rubric referenced by a file uploaded via the Files API.
71296730
from line 6734
71336734
71346735 - `type: "file"`
71356736
7136 - `"file"`
7137
7138 - `BetaManagedAgentsTextRubric object { content, type }`
6737 - `BetaManagedAgentsTextRubric object`
71396738
71406739 Rubric content provided inline as text.
71416740
from line 6744
71456744
71466745 - `type: "text"`
71476746
7148 - `"text"`
7149
71506747 - `type: "user.define_outcome"`
71516748
7152 - `"user.define_outcome"`
7153
71546749 - `max_iterations: optional number or null`
71556750
71566751 Eval→revision cycles before giving up. Default 3, max 20.
71576752
7158 - `BetaManagedAgentsDeploymentSystemMessageEvent object { content, type }`
6753 format: int32
6754
6755 - `BetaManagedAgentsDeploymentSystemMessageEvent object`
71596756
71606757 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.
71616758
from line 6764
71676764
71686765 The text content.
71696766
6767 minLength: 1
6768
71706769 - `type: "text"`
71716770
7172 - `"text"`
7173
71746771 - `type: "system.message"`
71756772
7176 - `"system.message"`
7177
71786773### Beta Managed Agents Deployment Initial Event Params
71796774
71806775- `BetaManagedAgentsDeploymentInitialEventParams = BetaManagedAgentsUserMessageEventParams or BetaManagedAgentsUserDefineOutcomeEventParams or BetaManagedAgentsSystemMessageEventParams`
71816776
71826777 An event sent to a session immediately after it is created. Supports `user.message`, `user.define_outcome`, and `system.message`.
71836778
7184 - `BetaManagedAgentsUserMessageEventParams object { content, type }`
6779 - `BetaManagedAgentsUserMessageEventParams object`
71856780
71866781 Parameters for sending a user message to the session.
71876782
from line 6784
71896784
71906785 Array of content blocks for the user message.
71916786
7192 - `BetaManagedAgentsTextBlock object { text, type }`
6787 - `BetaManagedAgentsTextBlock object`
71936788
71946789 Regular text content.
71956790
from line 6792
71976792
71986793 The text content.
71996794
6795 minLength: 1
6796
72006797 - `type: "text"`
72016798
7202 - `"text"`
7203
7204 - `BetaManagedAgentsImageBlock object { source, type }`
6799 - `BetaManagedAgentsImageBlock object`
72056800
72066801 Image content specified directly as base64 data or as a reference via a URL.
72076802
from line 6804
72096804
72106805 Union type for image source variants.
72116806
7212 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
6807 - `BetaManagedAgentsBase64ImageSource object`
72136808
72146809 Base64-encoded image data.
72156810
from line 6812
72176812
72186813 Base64-encoded image data.
72196814
6815 minLength: 1
6816
72206817 - `media_type: string`
72216818
72226819 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
72236820
6821 minLength: 1
6822
72246823 - `type: "base64"`
72256824
7226 - `"base64"`
7227
7228 - `BetaManagedAgentsURLImageSource object { type, url }`
6825 - `BetaManagedAgentsURLImageSource object`
72296826
72306827 Image referenced by URL.
72316828
72326829 - `type: "url"`
72336830
7234 - `"url"`
7235
72366831 - `url: string`
72376832
72386833 URL of the image to fetch.
72396834
7240 - `BetaManagedAgentsFileImageSource object { file_id, type }`
6835 minLength: 1
6836
6837 - `BetaManagedAgentsFileImageSource object`
72416838
72426839 Image referenced by file ID.
72436840
from line 6842
72456842
72466843 ID of a previously uploaded file.
72476844
6845 minLength: 1
6846
72486847 - `type: "file"`
72496848
7250 - `"file"`
7251
72526849 - `type: "image"`
72536850
7254 - `"image"`
7255
7256 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
6851 - `BetaManagedAgentsDocumentBlock object`
72576852
72586853 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
72596854
from line 6856
72616856
72626857 Union type for document source variants.
72636858
7264 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
6859 - `BetaManagedAgentsBase64DocumentSource object`
72656860
72666861 Base64-encoded document data.
72676862
from line 6864
72696864
72706865 Base64-encoded document data.
72716866
6867 minLength: 1
6868
72726869 - `media_type: string`
72736870
72746871 MIME type of the document (e.g., "application/pdf").
72756872
6873 minLength: 1
6874
72766875 - `type: "base64"`
72776876
7278 - `"base64"`
7279
7280 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
6877 - `BetaManagedAgentsPlainTextDocumentSource object`
72816878
72826879 Plain text document content.
72836880
from line 6882
72856882
72866883 The plain text content.
72876884
6885 minLength: 1
6886
72886887 - `media_type: "text/plain"`
72896888
72906889 MIME type of the text content. Must be "text/plain".
72916890
7292 - `"text/plain"`
7293
72946891 - `type: "text"`
72956892
7296 - `"text"`
7297
7298 - `BetaManagedAgentsURLDocumentSource object { type, url }`
6893 - `BetaManagedAgentsURLDocumentSource object`
72996894
73006895 Document referenced by URL.
73016896
73026897 - `type: "url"`
73036898
7304 - `"url"`
7305
73066899 - `url: string`
73076900
73086901 URL of the document to fetch.
73096902
7310 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
6903 minLength: 1
6904
6905 - `BetaManagedAgentsFileDocumentSource object`
73116906
73126907 Document referenced by file ID.
73136908
from line 6910
73156910
73166911 ID of a previously uploaded file.
73176912
6913 minLength: 1
6914
73186915 - `type: "file"`
73196916
7320 - `"file"`
7321
73226917 - `type: "document"`
73236918
7324 - `"document"`
7325
73266919 - `context: optional string or null`
73276920
73286921 Additional context about the document for the model.
from line 6924
73316924
73326925 The title of the document.
73336926
7334 - `BetaManagedAgentsRedactedBlock object { type }`
6927 - `BetaManagedAgentsRedactedBlock object`
73356928
73366929 Placeholder for content withheld by Anthropic model policy.
73376930
73386931 - `type: "redacted"`
73396932
7340 - `"redacted"`
7341
73426933 - `type: "user.message"`
73436934
7344 - `"user.message"`
7345
7346 - `BetaManagedAgentsUserDefineOutcomeEventParams object { description, rubric, type, max_iterations }`
6935 - `BetaManagedAgentsUserDefineOutcomeEventParams object`
73476936
73486937 Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.
73496938
from line 6944
73556944
73566945 Rubric for grading the quality of an outcome.
73576946
7358 - `BetaManagedAgentsFileRubricParams object { file_id, type }`
6947 - `BetaManagedAgentsFileRubricParams object`
73596948
73606949 Rubric referenced by a file uploaded via the Files API.
73616950
from line 6954
73656954
73666955 - `type: "file"`
73676956
7368 - `"file"`
7369
7370 - `BetaManagedAgentsTextRubricParams object { content, type }`
6957 - `BetaManagedAgentsTextRubricParams object`
73716958
73726959 Rubric content provided inline as text.
73736960
from line 6962
73756962
73766963 Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.
73776964
6965 maxLength: 262144
6966
73786967 - `type: "text"`
73796968
7380 - `"text"`
7381
73826969 - `type: "user.define_outcome"`
73836970
7384 - `"user.define_outcome"`
7385
73866971 - `max_iterations: optional number or null`
73876972
73886973 Eval→revision cycles before giving up. Default 3, max 20.
73896974
7390 - `BetaManagedAgentsSystemMessageEventParams object { content, type }`
6975 format: int32
6976
6977 - `BetaManagedAgentsSystemMessageEventParams object`
73916978
73926979 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.
73936980
from line 6986
73996986
74006987 The text content.
74016988
6989 minLength: 1
6990
74026991 - `type: "text"`
74036992
7404 - `"text"`
7405
74066993 - `type: "system.message"`
74076994
7408 - `"system.message"`
7409
74106995### Beta Managed Agents Deployment Paused Reason
74116996
74126997- `BetaManagedAgentsDeploymentPausedReason = BetaManagedAgentsManualDeploymentPausedReason or BetaManagedAgentsErrorDeploymentPausedReason`
74136998
74146999 Why a deployment is paused. Non-null exactly when `status` is `paused`.
74157000
7416 - `BetaManagedAgentsManualDeploymentPausedReason object { type }`
7001 - `BetaManagedAgentsManualDeploymentPausedReason object`
74177002
74187003 The caller invoked the pause endpoint on the deployment.
74197004
74207005 - `type: "manual"`
74217006
7422 - `"manual"`
7423
7424 - `BetaManagedAgentsErrorDeploymentPausedReason object { error, type }`
7007 - `BetaManagedAgentsErrorDeploymentPausedReason object`
74257008
74267009 A scheduled fire recorded a failed run whose error auto-pauses the deployment.
74277010
from line 7012
74297012
74307013 The error that triggered an auto-pause. Matches the failed run's `error.type`.
74317014
7432 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object { type }`
7015 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object`
74337016
74347017 The deployment's environment was archived.
74357018
74367019 - `type: "environment_archived_error"`
74377020
7438 - `"environment_archived_error"`
7439
7440 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object { type }`
7021 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object`
74417022
74427023 The deployment's agent was archived.
74437024
74447025 - `type: "agent_archived_error"`
74457026
7446 - `"agent_archived_error"`
7447
7448 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object { type }`
7027 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object`
74497028
74507029 The deployment's environment no longer exists.
74517030
74527031 - `type: "environment_not_found_error"`
74537032
7454 - `"environment_not_found_error"`
7455
7456 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object { type }`
7033 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object`
74577034
74587035 A vault referenced by the deployment no longer exists.
74597036
74607037 - `type: "vault_not_found_error"`
74617038
7462 - `"vault_not_found_error"`
7463
7464 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object { type }`
7039 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object`
74657040
74667041 A file resource referenced by the deployment no longer exists.
74677042
74687043 - `type: "file_not_found_error"`
74697044
7470 - `"file_not_found_error"`
7471
7472 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object { type }`
7045 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object`
74737046
74747047 A referenced resource no longer exists and its kind was not reported.
74757048
74767049 - `type: "session_resource_not_found_error"`
74777050
7478 - `"session_resource_not_found_error"`
7479
7480 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object { type }`
7051 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object`
74817052
74827053 The deployment's workspace was archived.
74837054
74847055 - `type: "workspace_archived_error"`
74857056
7486 - `"workspace_archived_error"`
7487
7488 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object { type }`
7057 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object`
74897058
74907059 The deployment's organization is disabled.
74917060
74927061 - `type: "organization_disabled_error"`
74937062
7494 - `"organization_disabled_error"`
7495
7496 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object { type }`
7063 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object`
74977064
74987065 A memory store referenced by the deployment is archived.
74997066
75007067 - `type: "memory_store_archived_error"`
75017068
7502 - `"memory_store_archived_error"`
7503
7504 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object { type }`
7069 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object`
75057070
75067071 A skill referenced by the deployment's agent no longer exists.
75077072
75087073 - `type: "skill_not_found_error"`
75097074
7510 - `"skill_not_found_error"`
7511
7512 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object { type }`
7075 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object`
75137076
75147077 A vault referenced by the deployment is archived.
75157078
75167079 - `type: "vault_archived_error"`
75177080
7518 - `"vault_archived_error"`
7519
7520 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object { type }`
7081 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object`
75217082
75227083 An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.
75237084
75247085 - `type: "unknown_error"`
75257086
7526 - `"unknown_error"`
7527
7528 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object { type }`
7087 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object`
75297088
75307089 The deployment configures resources, but its environment is self-hosted and cannot mount them.
75317090
75327091 - `type: "self_hosted_resources_unsupported_error"`
75337092
7534 - `"self_hosted_resources_unsupported_error"`
7535
7536 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object { type }`
7093 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object`
75377094
75387095 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
75397096
75407097 - `type: "mcp_egress_blocked_error"`
75417098
7542 - `"mcp_egress_blocked_error"`
7543
75447099 - `type: "error"`
75457100
7546 - `"error"`
7547
75487101### Beta Managed Agents Deployment Paused Reason Error
75497102
75507103- `BetaManagedAgentsDeploymentPausedReasonError = BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError or BetaManagedAgentsAgentArchivedDeploymentPausedReasonError or BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError or 11 more`
75517104
75527105 The error that triggered an auto-pause. Matches the failed run's `error.type`.
75537106
7554 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object { type }`
7107 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object`
75557108
75567109 The deployment's environment was archived.
75577110
75587111 - `type: "environment_archived_error"`
75597112
7560 - `"environment_archived_error"`
7561
7562 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object { type }`
7113 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object`
75637114
75647115 The deployment's agent was archived.
75657116
75667117 - `type: "agent_archived_error"`
75677118
7568 - `"agent_archived_error"`
7569
7570 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object { type }`
7119 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object`
75717120
75727121 The deployment's environment no longer exists.
75737122
75747123 - `type: "environment_not_found_error"`
75757124
7576 - `"environment_not_found_error"`
7577
7578 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object { type }`
7125 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object`
75797126
75807127 A vault referenced by the deployment no longer exists.
75817128
75827129 - `type: "vault_not_found_error"`
75837130
7584 - `"vault_not_found_error"`
7585
7586 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object { type }`
7131 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object`
75877132
75887133 A file resource referenced by the deployment no longer exists.
75897134
75907135 - `type: "file_not_found_error"`
75917136
7592 - `"file_not_found_error"`
7593
7594 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object { type }`
7137 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object`
75957138
75967139 A referenced resource no longer exists and its kind was not reported.
75977140
75987141 - `type: "session_resource_not_found_error"`
75997142
7600 - `"session_resource_not_found_error"`
7601
7602 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object { type }`
7143 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object`
76037144
76047145 The deployment's workspace was archived.
76057146
76067147 - `type: "workspace_archived_error"`
76077148
7608 - `"workspace_archived_error"`
7609
7610 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object { type }`
7149 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object`
76117150
76127151 The deployment's organization is disabled.
76137152
76147153 - `type: "organization_disabled_error"`
76157154
7616 - `"organization_disabled_error"`
7617
7618 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object { type }`
7155 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object`
76197156
76207157 A memory store referenced by the deployment is archived.
76217158
76227159 - `type: "memory_store_archived_error"`
76237160
7624 - `"memory_store_archived_error"`
7625
7626 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object { type }`
7161 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object`
76277162
76287163 A skill referenced by the deployment's agent no longer exists.
76297164
76307165 - `type: "skill_not_found_error"`
76317166
7632 - `"skill_not_found_error"`
7633
7634 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object { type }`
7167 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object`
76357168
76367169 A vault referenced by the deployment is archived.
76377170
76387171 - `type: "vault_archived_error"`
76397172
7640 - `"vault_archived_error"`
7641
7642 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object { type }`
7173 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object`
76437174
76447175 An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.
76457176
76467177 - `type: "unknown_error"`
76477178
7648 - `"unknown_error"`
7649
7650 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object { type }`
7179 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object`
76517180
76527181 The deployment configures resources, but its environment is self-hosted and cannot mount them.
76537182
76547183 - `type: "self_hosted_resources_unsupported_error"`
76557184
7656 - `"self_hosted_resources_unsupported_error"`
7657
7658 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object { type }`
7185 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object`
76597186
76607187 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
76617188
76627189 - `type: "mcp_egress_blocked_error"`
76637190
7664 - `"mcp_egress_blocked_error"`
7665
76667191### Beta Managed Agents Deployment Status
76677192
76687193- `BetaManagedAgentsDeploymentStatus = "active" or "paused"`
from line 7200
76757200
76767201### Beta Managed Agents Deployment System Message Event
76777202
7678- `BetaManagedAgentsDeploymentSystemMessageEvent object { content, type }`
7203- `BetaManagedAgentsDeploymentSystemMessageEvent object`
76797204
76807205 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.
76817206
from line 7212
76877212
76887213 The text content.
76897214
7215 minLength: 1
7216
76907217 - `type: "text"`
76917218
7692 - `"text"`
7693
76947219 - `type: "system.message"`
76957220
7696 - `"system.message"`
7697
76987221### Beta Managed Agents Deployment User Define Outcome Event
76997222
7700- `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object { description, rubric, type, max_iterations }`
7223- `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`
77017224
77027225 An outcome the agent should work toward. The agent begins work on receipt.
77037226
from line 7232
77097232
77107233 Rubric for grading the quality of an outcome.
77117234
7712 - `BetaManagedAgentsFileRubric object { file_id, type }`
7235 - `BetaManagedAgentsFileRubric object`
77137236
77147237 Rubric referenced by a file uploaded via the Files API.
77157238
from line 7242
77197242
77207243 - `type: "file"`
77217244
7722 - `"file"`
7723
7724 - `BetaManagedAgentsTextRubric object { content, type }`
7245 - `BetaManagedAgentsTextRubric object`
77257246
77267247 Rubric content provided inline as text.
77277248
from line 7252
77317252
77327253 - `type: "text"`
77337254
7734 - `"text"`
7735
77367255 - `type: "user.define_outcome"`
77377256
7738 - `"user.define_outcome"`
7739
77407257 - `max_iterations: optional number or null`
77417258
77427259 Eval→revision cycles before giving up. Default 3, max 20.
77437260
7261 format: int32
7262
77447263### Beta Managed Agents Deployment User Message Event
77457264
7746- `BetaManagedAgentsDeploymentUserMessageEvent object { content, type }`
7265- `BetaManagedAgentsDeploymentUserMessageEvent object`
77477266
77487267 A user message sent to the session.
77497268
from line 7270
77517270
77527271 Array of content blocks for the user message.
77537272
7754 - `BetaManagedAgentsTextBlock object { text, type }`
7273 - `BetaManagedAgentsTextBlock object`
77557274
77567275 Regular text content.
77577276
from line 7278
77597278
77607279 The text content.
77617280
7281 minLength: 1
7282
77627283 - `type: "text"`
77637284
7764 - `"text"`
7765
7766 - `BetaManagedAgentsImageBlock object { source, type }`
7285 - `BetaManagedAgentsImageBlock object`
77677286
77687287 Image content specified directly as base64 data or as a reference via a URL.
77697288
from line 7290
77717290
77727291 Union type for image source variants.
77737292
7774 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
7293 - `BetaManagedAgentsBase64ImageSource object`
77757294
77767295 Base64-encoded image data.
77777296
from line 7298
77797298
77807299 Base64-encoded image data.
77817300
7301 minLength: 1
7302
77827303 - `media_type: string`
77837304
77847305 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
77857306
7307 minLength: 1
7308
77867309 - `type: "base64"`
77877310
7788 - `"base64"`
7789
7790 - `BetaManagedAgentsURLImageSource object { type, url }`
7311 - `BetaManagedAgentsURLImageSource object`
77917312
77927313 Image referenced by URL.
77937314
77947315 - `type: "url"`
77957316
7796 - `"url"`
7797
77987317 - `url: string`
77997318
78007319 URL of the image to fetch.
78017320
7802 - `BetaManagedAgentsFileImageSource object { file_id, type }`
7321 minLength: 1
7322
7323 - `BetaManagedAgentsFileImageSource object`
78037324
78047325 Image referenced by file ID.
78057326
from line 7328
78077328
78087329 ID of a previously uploaded file.
78097330
7331 minLength: 1
7332
78107333 - `type: "file"`
78117334
7812 - `"file"`
7813
78147335 - `type: "image"`
78157336
7816 - `"image"`
7817
7818 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
7337 - `BetaManagedAgentsDocumentBlock object`
78197338
78207339 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
78217340
from line 7342
78237342
78247343 Union type for document source variants.
78257344
7826 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
7345 - `BetaManagedAgentsBase64DocumentSource object`
78277346
78287347 Base64-encoded document data.
78297348
from line 7350
78317350
78327351 Base64-encoded document data.
78337352
7353 minLength: 1
7354
78347355 - `media_type: string`
78357356
78367357 MIME type of the document (e.g., "application/pdf").
78377358
7359 minLength: 1
7360
78387361 - `type: "base64"`
78397362
7840 - `"base64"`
7841
7842 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
7363 - `BetaManagedAgentsPlainTextDocumentSource object`
78437364
78447365 Plain text document content.
78457366
from line 7368
78477368
78487369 The plain text content.
78497370
7371 minLength: 1
7372
78507373 - `media_type: "text/plain"`
78517374
78527375 MIME type of the text content. Must be "text/plain".
78537376
7854 - `"text/plain"`
7855
78567377 - `type: "text"`
78577378
7858 - `"text"`
7859
7860 - `BetaManagedAgentsURLDocumentSource object { type, url }`
7379 - `BetaManagedAgentsURLDocumentSource object`
78617380
78627381 Document referenced by URL.
78637382
78647383 - `type: "url"`
78657384
7866 - `"url"`
7867
78687385 - `url: string`
78697386
78707387 URL of the document to fetch.
78717388
7872 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
7389 minLength: 1
7390
7391 - `BetaManagedAgentsFileDocumentSource object`
78737392
78747393 Document referenced by file ID.
78757394
from line 7396
78777396
78787397 ID of a previously uploaded file.
78797398
7399 minLength: 1
7400
78807401 - `type: "file"`
78817402
7882 - `"file"`
7883
78847403 - `type: "document"`
78857404
7886 - `"document"`
7887
78887405 - `context: optional string or null`
78897406
78907407 Additional context about the document for the model.
from line 7410
78937410
78947411 The title of the document.
78957412
7896 - `BetaManagedAgentsRedactedBlock object { type }`
7413 - `BetaManagedAgentsRedactedBlock object`
78977414
78987415 Placeholder for content withheld by Anthropic model policy.
78997416
79007417 - `type: "redacted"`
79017418
7902 - `"redacted"`
7903
79047419 - `type: "user.message"`
79057420
7906 - `"user.message"`
7907
79087421### Beta Managed Agents Environment Archived Deployment Paused Reason Error
79097422
7910- `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object { type }`
7423- `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object`
79117424
79127425 The deployment's environment was archived.
79137426
79147427 - `type: "environment_archived_error"`
79157428
7916 - `"environment_archived_error"`
7917
79187429### Beta Managed Agents Environment Not Found Deployment Paused Reason Error
79197430
7920- `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object { type }`
7431- `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object`
79217432
79227433 The deployment's environment no longer exists.
79237434
79247435 - `type: "environment_not_found_error"`
79257436
7926 - `"environment_not_found_error"`
7927
79287437### Beta Managed Agents Error Deployment Paused Reason
79297438
7930- `BetaManagedAgentsErrorDeploymentPausedReason object { error, type }`
7439- `BetaManagedAgentsErrorDeploymentPausedReason object`
79317440
79327441 A scheduled fire recorded a failed run whose error auto-pauses the deployment.
79337442
from line 7444
79357444
79367445 The error that triggered an auto-pause. Matches the failed run's `error.type`.
79377446
7938 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object { type }`
7447 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object`
79397448
79407449 The deployment's environment was archived.
79417450
79427451 - `type: "environment_archived_error"`
79437452
7944 - `"environment_archived_error"`
7945
7946 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object { type }`
7453 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object`
79477454
79487455 The deployment's agent was archived.
79497456
79507457 - `type: "agent_archived_error"`
79517458
7952 - `"agent_archived_error"`
7953
7954 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object { type }`
7459 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object`
79557460
79567461 The deployment's environment no longer exists.
79577462
79587463 - `type: "environment_not_found_error"`
79597464
7960 - `"environment_not_found_error"`
7961
7962 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object { type }`
7465 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object`
79637466
79647467 A vault referenced by the deployment no longer exists.
79657468
79667469 - `type: "vault_not_found_error"`
79677470
7968 - `"vault_not_found_error"`
7969
7970 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object { type }`
7471 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object`
79717472
79727473 A file resource referenced by the deployment no longer exists.
79737474
79747475 - `type: "file_not_found_error"`
79757476
7976 - `"file_not_found_error"`
7977
7978 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object { type }`
7477 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object`
79797478
79807479 A referenced resource no longer exists and its kind was not reported.
79817480
79827481 - `type: "session_resource_not_found_error"`
79837482
7984 - `"session_resource_not_found_error"`
7985
7986 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object { type }`
7483 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object`
79877484
79887485 The deployment's workspace was archived.
79897486
79907487 - `type: "workspace_archived_error"`
79917488
7992 - `"workspace_archived_error"`
7993
7994 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object { type }`
7489 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object`
79957490
79967491 The deployment's organization is disabled.
79977492
79987493 - `type: "organization_disabled_error"`
79997494
8000 - `"organization_disabled_error"`
8001
8002 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object { type }`
7495 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object`
80037496
80047497 A memory store referenced by the deployment is archived.
80057498
80067499 - `type: "memory_store_archived_error"`
80077500
8008 - `"memory_store_archived_error"`
8009
8010 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object { type }`
7501 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object`
80117502
80127503 A skill referenced by the deployment's agent no longer exists.
80137504
80147505 - `type: "skill_not_found_error"`
80157506
8016 - `"skill_not_found_error"`
8017
8018 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object { type }`
7507 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object`
80197508
80207509 A vault referenced by the deployment is archived.
80217510
80227511 - `type: "vault_archived_error"`
80237512
8024 - `"vault_archived_error"`
8025
8026 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object { type }`
7513 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object`
80277514
80287515 An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.
80297516
80307517 - `type: "unknown_error"`
80317518
8032 - `"unknown_error"`
8033
8034 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object { type }`
7519 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object`
80357520
80367521 The deployment configures resources, but its environment is self-hosted and cannot mount them.
80377522
80387523 - `type: "self_hosted_resources_unsupported_error"`
80397524
8040 - `"self_hosted_resources_unsupported_error"`
8041
8042 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object { type }`
7525 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object`
80437526
80447527 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
80457528
80467529 - `type: "mcp_egress_blocked_error"`
80477530
8048 - `"mcp_egress_blocked_error"`
8049
80507531 - `type: "error"`
80517532
8052 - `"error"`
8053
80547533### Beta Managed Agents File Not Found Deployment Paused Reason Error
80557534
8056- `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object { type }`
7535- `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object`
80577536
80587537 A file resource referenced by the deployment no longer exists.
80597538
80607539 - `type: "file_not_found_error"`
80617540
8062 - `"file_not_found_error"`
8063
80647541### Beta Managed Agents File Resource Config
80657542
8066- `BetaManagedAgentsFileResourceConfig object { file_id, type, mount_path }`
7543- `BetaManagedAgentsFileResourceConfig object`
80677544
80687545 A file mounted into each session's container.
80697546
from line 7550
80737550
80747551 - `type: "file"`
80757552
8076 - `"file"`
8077
80787553 - `mount_path: optional string or null`
80797554
80807555 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
80817556
80827557### Beta Managed Agents GitHub Repository Resource Config
80837558
8084- `BetaManagedAgentsGitHubRepositoryResourceConfig object { type, url, checkout, mount_path }`
7559- `BetaManagedAgentsGitHubRepositoryResourceConfig object`
80857560
80867561 A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.
80877562
80887563 - `type: "github_repository"`
80897564
8090 - `"github_repository"`
8091
80927565 - `url: string`
80937566
80947567 Github URL of the repository
from line 7570
80977570
80987571 Branch or commit to check out. Defaults to the repository's default branch.
80997572
8100 - `BetaManagedAgentsBranchCheckout object { name, type }`
7573 - `BetaManagedAgentsBranchCheckout object`
81017574
81027575 - `name: string`
81037576
81047577 Branch name to check out.
81057578
7579 minLength: 1, maxLength: 255
7580
81067581 - `type: "branch"`
81077582
8108 - `"branch"`
8109
8110 - `BetaManagedAgentsCommitCheckout object { sha, type }`
7583 - `BetaManagedAgentsCommitCheckout object`
81117584
81127585 - `sha: string`
81137586
81147587 Full commit SHA to check out.
81157588
7589 minLength: 7, maxLength: 64
7590
81167591 - `type: "commit"`
81177592
8118 - `"commit"`
8119
81207593 - `mount_path: optional string or null`
81217594
81227595 Mount path in the container. Defaults to `/workspace/<repo-name>`.
81237596
81247597### Beta Managed Agents Manual Deployment Paused Reason
81257598
8126- `BetaManagedAgentsManualDeploymentPausedReason object { type }`
7599- `BetaManagedAgentsManualDeploymentPausedReason object`
81277600
81287601 The caller invoked the pause endpoint on the deployment.
81297602
81307603 - `type: "manual"`
81317604
8132 - `"manual"`
8133
81347605### Beta Managed Agents MCP Egress Blocked Deployment Paused Reason Error
81357606
8136- `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object { type }`
7607- `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object`
81377608
81387609 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
81397610
81407611 - `type: "mcp_egress_blocked_error"`
81417612
8142 - `"mcp_egress_blocked_error"`
8143
81447613### Beta Managed Agents Memory Store Archived Deployment Paused Reason Error
81457614
8146- `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object { type }`
7615- `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object`
81477616
81487617 A memory store referenced by the deployment is archived.
81497618
81507619 - `type: "memory_store_archived_error"`
81517620
8152 - `"memory_store_archived_error"`
8153
81547621### Beta Managed Agents Memory Store Resource Config
81557622
8156- `BetaManagedAgentsMemoryStoreResourceConfig object { memory_store_id, type, access, instructions }`
7623- `BetaManagedAgentsMemoryStoreResourceConfig object`
81577624
81587625 A memory store attached to each session created from this deployment.
81597626
from line 7630
81637630
81647631 - `type: "memory_store"`
81657632
8166 - `"memory_store"`
8167
81687633 - `access: optional "read_write" or "read_only" or null`
81697634
81707635 Access mode for an attached memory store.
from line 7644
81797644
81807645### Beta Managed Agents Organization Disabled Deployment Paused Reason Error
81817646
8182- `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object { type }`
7647- `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object`
81837648
81847649 The deployment's organization is disabled.
81857650
81867651 - `type: "organization_disabled_error"`
81877652
8188 - `"organization_disabled_error"`
8189
81907653### Beta Managed Agents Schedule
81917654
8192- `BetaManagedAgentsSchedule object { expression, timezone, type, 2 more }`
7655- `BetaManagedAgentsSchedule object`
81937656
81947657 5-field POSIX cron schedule with computed runtime timestamps.
81957658
from line 7660
81977660
81987661 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).
81997662
7663 minLength: 1, maxLength: 256
7664
82007665 - `timezone: string`
82017666
82027667 IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").
82037668
7669 minLength: 1
7670
82047671 - `type: "cron"`
82057672
8206 - `"cron"`
8207
82087673 - `last_run_at: optional string or null`
82097674
82107675 A timestamp in RFC 3339 format
82117676
7677 format: date-time
7678
82127679 - `upcoming_runs_at: optional array of string`
82137680
82147681 Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.
82157682
82167683### Beta Managed Agents Schedule Params
82177684
8218- `BetaManagedAgentsScheduleParams object { expression, timezone, type }`
7685- `BetaManagedAgentsScheduleParams object`
82197686
82207687 5-field POSIX cron schedule. Literal wall-clock matching in the configured timezone.
82217688
from line 7690
82237690
82247691 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).
82257692
7693 minLength: 1, maxLength: 256
7694
82267695 - `timezone: string`
82277696
82287697 Required. IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). Validated against the IANA timezone database.
82297698
7699 minLength: 1
7700
82307701 - `type: "cron"`
82317702
8232 - `"cron"`
8233
82347703### Beta Managed Agents Self Hosted Resources Unsupported Deployment Paused Reason Error
82357704
8236- `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object { type }`
7705- `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object`
82377706
82387707 The deployment configures resources, but its environment is self-hosted and cannot mount them.
82397708
82407709 - `type: "self_hosted_resources_unsupported_error"`
82417710
8242 - `"self_hosted_resources_unsupported_error"`
8243
82447711### Beta Managed Agents Session Resource Config
82457712
82467713- `BetaManagedAgentsSessionResourceConfig = BetaManagedAgentsGitHubRepositoryResourceConfig or BetaManagedAgentsFileResourceConfig or BetaManagedAgentsMemoryStoreResourceConfig`
82477714
82487715 A configured session resource. Echoes the input minus write-only credentials.
82497716
8250 - `BetaManagedAgentsGitHubRepositoryResourceConfig object { type, url, checkout, mount_path }`
7717 - `BetaManagedAgentsGitHubRepositoryResourceConfig object`
82517718
82527719 A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.
82537720
82547721 - `type: "github_repository"`
82557722
8256 - `"github_repository"`
8257
82587723 - `url: string`
82597724
82607725 Github URL of the repository
from line 7728
82637728
82647729 Branch or commit to check out. Defaults to the repository's default branch.
82657730
8266 - `BetaManagedAgentsBranchCheckout object { name, type }`
7731 - `BetaManagedAgentsBranchCheckout object`
82677732
82687733 - `name: string`
82697734
82707735 Branch name to check out.
82717736
7737 minLength: 1, maxLength: 255
7738
82727739 - `type: "branch"`
82737740
8274 - `"branch"`
8275
8276 - `BetaManagedAgentsCommitCheckout object { sha, type }`
7741 - `BetaManagedAgentsCommitCheckout object`
82777742
82787743 - `sha: string`
82797744
82807745 Full commit SHA to check out.
82817746
7747 minLength: 7, maxLength: 64
7748
82827749 - `type: "commit"`
82837750
8284 - `"commit"`
8285
82867751 - `mount_path: optional string or null`
82877752
82887753 Mount path in the container. Defaults to `/workspace/<repo-name>`.
82897754
8290 - `BetaManagedAgentsFileResourceConfig object { file_id, type, mount_path }`
7755 - `BetaManagedAgentsFileResourceConfig object`
82917756
82927757 A file mounted into each session's container.
82937758
from line 7762
82977762
82987763 - `type: "file"`
82997764
8300 - `"file"`
8301
83027765 - `mount_path: optional string or null`
83037766
83047767 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
83057768
8306 - `BetaManagedAgentsMemoryStoreResourceConfig object { memory_store_id, type, access, instructions }`
7769 - `BetaManagedAgentsMemoryStoreResourceConfig object`
83077770
83087771 A memory store attached to each session created from this deployment.
83097772
from line 7776
83137776
83147777 - `type: "memory_store"`
83157778
8316 - `"memory_store"`
8317
83187779 - `access: optional "read_write" or "read_only" or null`
83197780
83207781 Access mode for an attached memory store.
from line 7790
83297790
83307791### Beta Managed Agents Session Resource Not Found Deployment Paused Reason Error
83317792
8332- `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object { type }`
7793- `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object`
83337794
83347795 A referenced resource no longer exists and its kind was not reported.
83357796
83367797 - `type: "session_resource_not_found_error"`
83377798
8338 - `"session_resource_not_found_error"`
8339
83407799### Beta Managed Agents Skill Not Found Deployment Paused Reason Error
83417800
8342- `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object { type }`
7801- `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object`
83437802
83447803 A skill referenced by the deployment's agent no longer exists.
83457804
83467805 - `type: "skill_not_found_error"`
83477806
8348 - `"skill_not_found_error"`
8349
83507807### Beta Managed Agents Unknown Deployment Paused Reason Error
83517808
8352- `BetaManagedAgentsUnknownDeploymentPausedReasonError object { type }`
7809- `BetaManagedAgentsUnknownDeploymentPausedReasonError object`
83537810
83547811 An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.
83557812
83567813 - `type: "unknown_error"`
83577814
8358 - `"unknown_error"`
8359
83607815### Beta Managed Agents Vault Archived Deployment Paused Reason Error
83617816
8362- `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object { type }`
7817- `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object`
83637818
83647819 A vault referenced by the deployment is archived.
83657820
83667821 - `type: "vault_archived_error"`
83677822
8368 - `"vault_archived_error"`
8369
83707823### Beta Managed Agents Vault Not Found Deployment Paused Reason Error
83717824
8372- `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object { type }`
7825- `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object`
83737826
83747827 A vault referenced by the deployment no longer exists.
83757828
83767829 - `type: "vault_not_found_error"`
83777830
8378 - `"vault_not_found_error"`
8379
83807831### Beta Managed Agents Workspace Archived Deployment Paused Reason Error
83817832
8382- `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object { type }`
7833- `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object`
83837834
83847835 The deployment's workspace was archived.
83857836
83867837 - `type: "workspace_archived_error"`
8387
8388 - `"workspace_archived_error"`
83897838
api/beta/deployments/archive Changed · +91 / -142 lines
# Archive Deployment ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Archive Deployment ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Archive Deployment
3url: https://platform.claude.com/docs/en/api/beta/deployments/archive
4---
1# Archive Deployment
52
6## Archive Deployment
3**POST** `/v1/deployments/{deployment_id}/archive`
74
8**post** `/v1/deployments/{deployment_id}/archive`
9
105Archive Deployment
116
12### Path Parameters
7## Path parameters
138
149- `deployment_id: string`
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Returns
89## Returns
9590
96- `BetaManagedAgentsDeployment object { id, agent, archived_at, 14 more }`
91- `BetaManagedAgentsDeployment object`
9792
9893 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.
9994
from line 104
109104
110105 - `type: "agent"`
111106
112 - `"agent"`
113
114107 - `version: number`
115108
109 format: int32
110
116111 - `archived_at: string or null`
117112
118113 A timestamp in RFC 3339 format
119114
115 format: date-time
116
120117 - `created_at: string`
121118
122119 A timestamp in RFC 3339 format
123120
121 format: date-time
122
124123 - `description: string or null`
125124
126125 Description of what the deployment does.
from line 132
133132
134133 Events sent to each session immediately after creation.
135134
136 - `BetaManagedAgentsDeploymentUserMessageEvent object { content, type }`
135 - `BetaManagedAgentsDeploymentUserMessageEvent object`
137136
138137 A user message sent to the session.
139138
from line 140
141140
142141 Array of content blocks for the user message.
143142
144 - `BetaManagedAgentsTextBlock object { text, type }`
143 - `BetaManagedAgentsTextBlock object`
145144
146145 Regular text content.
147146
from line 148
149148
150149 The text content.
151150
151 minLength: 1
152
152153 - `type: "text"`
153154
154 - `"text"`
155 - `BetaManagedAgentsImageBlock object`
155156
156 - `BetaManagedAgentsImageBlock object { source, type }`
157
158157 Image content specified directly as base64 data or as a reference via a URL.
159158
160159 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
from line 160
161160
162161 Union type for image source variants.
163162
164 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
163 - `BetaManagedAgentsBase64ImageSource object`
165164
166165 Base64-encoded image data.
167166
from line 168
169168
170169 Base64-encoded image data.
171170
171 minLength: 1
172
172173 - `media_type: string`
173174
174175 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
175176
177 minLength: 1
178
176179 - `type: "base64"`
177180
178 - `"base64"`
181 - `BetaManagedAgentsURLImageSource object`
179182
180 - `BetaManagedAgentsURLImageSource object { type, url }`
181
182183 Image referenced by URL.
183184
184185 - `type: "url"`
185186
186 - `"url"`
187
188187 - `url: string`
189188
190189 URL of the image to fetch.
191190
192 - `BetaManagedAgentsFileImageSource object { file_id, type }`
191 minLength: 1
193192
193 - `BetaManagedAgentsFileImageSource object`
194
194195 Image referenced by file ID.
195196
196197 - `file_id: string`
from line 198
197198
198199 ID of a previously uploaded file.
199200
201 minLength: 1
202
200203 - `type: "file"`
201204
202 - `"file"`
203
204205 - `type: "image"`
205206
206 - `"image"`
207 - `BetaManagedAgentsDocumentBlock object`
207208
208 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
209
210209 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
211210
212211 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
from line 212
213212
214213 Union type for document source variants.
215214
216 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
215 - `BetaManagedAgentsBase64DocumentSource object`
217216
218217 Base64-encoded document data.
219218
from line 220
221220
222221 Base64-encoded document data.
223222
223 minLength: 1
224
224225 - `media_type: string`
225226
226227 MIME type of the document (e.g., "application/pdf").
227228
229 minLength: 1
230
228231 - `type: "base64"`
229232
230 - `"base64"`
233 - `BetaManagedAgentsPlainTextDocumentSource object`
231234
232 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
233
234235 Plain text document content.
235236
236237 - `data: string`
from line 238
237238
238239 The plain text content.
239240
241 minLength: 1
242
240243 - `media_type: "text/plain"`
241244
242245 MIME type of the text content. Must be "text/plain".
243246
244 - `"text/plain"`
245
246247 - `type: "text"`
247248
248 - `"text"`
249 - `BetaManagedAgentsURLDocumentSource object`
249250
250 - `BetaManagedAgentsURLDocumentSource object { type, url }`
251
252251 Document referenced by URL.
253252
254253 - `type: "url"`
255254
256 - `"url"`
257
258255 - `url: string`
259256
260257 URL of the document to fetch.
261258
262 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
259 minLength: 1
263260
261 - `BetaManagedAgentsFileDocumentSource object`
262
264263 Document referenced by file ID.
265264
266265 - `file_id: string`
from line 266
267266
268267 ID of a previously uploaded file.
269268
269 minLength: 1
270
270271 - `type: "file"`
271272
272 - `"file"`
273
274273 - `type: "document"`
275274
276 - `"document"`
277
278275 - `context: optional string or null`
279276
280277 Additional context about the document for the model.
from line 280
283280
284281 The title of the document.
285282
286 - `BetaManagedAgentsRedactedBlock object { type }`
283 - `BetaManagedAgentsRedactedBlock object`
287284
288285 Placeholder for content withheld by Anthropic model policy.
289286
290287 - `type: "redacted"`
291288
292 - `"redacted"`
293
294289 - `type: "user.message"`
295290
296 - `"user.message"`
291 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`
297292
298 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object { description, rubric, type, max_iterations }`
299
300293 An outcome the agent should work toward. The agent begins work on receipt.
301294
302295 - `description: string`
from line 300
307300
308301 Rubric for grading the quality of an outcome.
309302
310 - `BetaManagedAgentsFileRubric object { file_id, type }`
303 - `BetaManagedAgentsFileRubric object`
311304
312305 Rubric referenced by a file uploaded via the Files API.
313306
from line 310
317310
318311 - `type: "file"`
319312
320 - `"file"`
313 - `BetaManagedAgentsTextRubric object`
321314
322 - `BetaManagedAgentsTextRubric object { content, type }`
323
324315 Rubric content provided inline as text.
325316
326317 - `content: string`
from line 320
329320
330321 - `type: "text"`
331322
332 - `"text"`
333
334323 - `type: "user.define_outcome"`
335324
336 - `"user.define_outcome"`
337
338325 - `max_iterations: optional number or null`
339326
340327 Eval→revision cycles before giving up. Default 3, max 20.
341328
342 - `BetaManagedAgentsDeploymentSystemMessageEvent object { content, type }`
329 format: int32
343330
331 - `BetaManagedAgentsDeploymentSystemMessageEvent object`
332
344333 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.
345334
346335 - `content: array of BetaManagedAgentsSystemContentBlock`
from line 340
351340
352341 The text content.
353342
343 minLength: 1
344
354345 - `type: "text"`
355346
356 - `"text"`
357
358347 - `type: "system.message"`
359348
360 - `"system.message"`
361
362349 - `metadata: map[string]`
363350
364351 Arbitrary key-value metadata. Maximum 16 pairs.
from line 358
371358
372359 Why a deployment is paused. Non-null exactly when `status` is `paused`.
373360
374 - `BetaManagedAgentsManualDeploymentPausedReason object { type }`
361 - `BetaManagedAgentsManualDeploymentPausedReason object`
375362
376363 The caller invoked the pause endpoint on the deployment.
377364
378365 - `type: "manual"`
379366
380 - `"manual"`
367 - `BetaManagedAgentsErrorDeploymentPausedReason object`
381368
382 - `BetaManagedAgentsErrorDeploymentPausedReason object { error, type }`
383
384369 A scheduled fire recorded a failed run whose error auto-pauses the deployment.
385370
386371 - `error: BetaManagedAgentsDeploymentPausedReasonError`
from line 372
387372
388373 The error that triggered an auto-pause. Matches the failed run's `error.type`.
389374
390 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object { type }`
375 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object`
391376
392377 The deployment's environment was archived.
393378
394379 - `type: "environment_archived_error"`
395380
396 - `"environment_archived_error"`
381 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object`
397382
398 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object { type }`
399
400383 The deployment's agent was archived.
401384
402385 - `type: "agent_archived_error"`
403386
404 - `"agent_archived_error"`
387 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object`
405388
406 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object { type }`
407
408389 The deployment's environment no longer exists.
409390
410391 - `type: "environment_not_found_error"`
411392
412 - `"environment_not_found_error"`
393 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object`
413394
414 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object { type }`
415
416395 A vault referenced by the deployment no longer exists.
417396
418397 - `type: "vault_not_found_error"`
419398
420 - `"vault_not_found_error"`
399 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object`
421400
422 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object { type }`
423
424401 A file resource referenced by the deployment no longer exists.
425402
426403 - `type: "file_not_found_error"`
427404
428 - `"file_not_found_error"`
405 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object`
429406
430 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object { type }`
431
432407 A referenced resource no longer exists and its kind was not reported.
433408
434409 - `type: "session_resource_not_found_error"`
435410
436 - `"session_resource_not_found_error"`
411 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object`
437412
438 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object { type }`
439
440413 The deployment's workspace was archived.
441414
442415 - `type: "workspace_archived_error"`
443416
444 - `"workspace_archived_error"`
417 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object`
445418
446 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object { type }`
447
448419 The deployment's organization is disabled.
449420
450421 - `type: "organization_disabled_error"`
451422
452 - `"organization_disabled_error"`
423 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object`
453424
454 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object { type }`
455
456425 A memory store referenced by the deployment is archived.
457426
458427 - `type: "memory_store_archived_error"`
459428
460 - `"memory_store_archived_error"`
429 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object`
461430
462 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object { type }`
463
464431 A skill referenced by the deployment's agent no longer exists.
465432
466433 - `type: "skill_not_found_error"`
467434
468 - `"skill_not_found_error"`
435 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object`
469436
470 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object { type }`
471
472437 A vault referenced by the deployment is archived.
473438
474439 - `type: "vault_archived_error"`
475440
476 - `"vault_archived_error"`
441 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object`
477442
478 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object { type }`
479
480443 An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.
481444
482445 - `type: "unknown_error"`
483446
484 - `"unknown_error"`
447 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object`
485448
486 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object { type }`
487
488449 The deployment configures resources, but its environment is self-hosted and cannot mount them.
489450
490451 - `type: "self_hosted_resources_unsupported_error"`
491452
492 - `"self_hosted_resources_unsupported_error"`
453 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object`
493454
494 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object { type }`
495
496455 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
497456
498457 - `type: "mcp_egress_blocked_error"`
499458
500 - `"mcp_egress_blocked_error"`
501
502459 - `type: "error"`
503460
504 - `"error"`
505
506461 - `resources: array of BetaManagedAgentsSessionResourceConfig`
507462
508463 Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.
509464
510 - `BetaManagedAgentsGitHubRepositoryResourceConfig object { type, url, checkout, mount_path }`
465 - `BetaManagedAgentsGitHubRepositoryResourceConfig object`
511466
512467 A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.
513468
514469 - `type: "github_repository"`
515470
516 - `"github_repository"`
517
518471 - `url: string`
519472
520473 Github URL of the repository
from line 476
523476
524477 Branch or commit to check out. Defaults to the repository's default branch.
525478
526 - `BetaManagedAgentsBranchCheckout object { name, type }`
479 - `BetaManagedAgentsBranchCheckout object`
527480
528481 - `name: string`
529482
530483 Branch name to check out.
531484
485 minLength: 1, maxLength: 255
486
532487 - `type: "branch"`
533488
534 - `"branch"`
489 - `BetaManagedAgentsCommitCheckout object`
535490
536 - `BetaManagedAgentsCommitCheckout object { sha, type }`
537
538491 - `sha: string`
539492
540493 Full commit SHA to check out.
541494
495 minLength: 7, maxLength: 64
496
542497 - `type: "commit"`
543498
544 - `"commit"`
545
546499 - `mount_path: optional string or null`
547500
548501 Mount path in the container. Defaults to `/workspace/<repo-name>`.
549502
550 - `BetaManagedAgentsFileResourceConfig object { file_id, type, mount_path }`
503 - `BetaManagedAgentsFileResourceConfig object`
551504
552505 A file mounted into each session's container.
553506
from line 510
557510
558511 - `type: "file"`
559512
560 - `"file"`
561
562513 - `mount_path: optional string or null`
563514
564515 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
565516
566 - `BetaManagedAgentsMemoryStoreResourceConfig object { memory_store_id, type, access, instructions }`
517 - `BetaManagedAgentsMemoryStoreResourceConfig object`
567518
568519 A memory store attached to each session created from this deployment.
569520
from line 524
573524
574525 - `type: "memory_store"`
575526
576 - `"memory_store"`
577
578527 - `access: optional "read_write" or "read_only" or null`
579528
580529 Access mode for an attached memory store.
from line 544
595544
596545 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).
597546
547 minLength: 1, maxLength: 256
548
598549 - `timezone: string`
599550
600551 IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").
601552
553 minLength: 1
554
602555 - `type: "cron"`
603556
604 - `"cron"`
605
606557 - `last_run_at: optional string or null`
607558
608559 A timestamp in RFC 3339 format
609560
561 format: date-time
562
610563 - `upcoming_runs_at: optional array of string`
611564
612565 Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.
from line 574
621574
622575 - `type: "deployment"`
623576
624 - `"deployment"`
625
626577 - `updated_at: string`
627578
628579 A timestamp in RFC 3339 format
629580
581 format: date-time
582
630583 - `vault_ids: array of string`
631584
632585 Vault IDs supplying stored credentials for sessions created from this deployment.
from line 600
647600
648601 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.
649602
650 - `"USD"`
651
652603 - `type: "limit"`
653604
654 - `"limit"`
605## Example
655606
656### Example
657
658```http
607```bash
659608curl https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/archive \
660609 -X POST \
661610 -H 'anthropic-version: 2023-06-01' \
from line 612
663612 -H "X-Api-Key: $ANTHROPIC_API_KEY"
664613```
665614
666#### Response
615### Response (200)
667616
668617```json
669618{
api/beta/deployments/create Changed · +169 / -218 lines
# Create Deployment ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Create Deployment ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Create Deployment
3url: https://platform.claude.com/docs/en/api/beta/deployments/create
4---
1# Create Deployment
52
6## Create Deployment
3**POST** `/v1/deployments`
74
8**post** `/v1/deployments`
9
105Create Deployment
116
12### Header Parameters
7## Headers
138
149- `"anthropic-beta": optional array of AnthropicBeta`
1510
from line 82
8782
8883 - `"mid-conversation-tool-changes-2026-07-01"`
8984
90### Body Parameters
85## Body parameters
9186
9287- `agent: string or BetaManagedAgentsAgentParams`
9388
from line 90
9590
9691 - `string`
9792
98 - `BetaManagedAgentsAgentParams object { id, type, version }`
93 - `BetaManagedAgentsAgentParams object`
9994
10095 Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version
10196
from line 98
10398
10499 The `agent` ID.
105100
101 minLength: 1, maxLength: 128
102
106103 - `type: "agent"`
107104
108 - `"agent"`
109
110105 - `version: optional number`
111106
112107 The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.
113108
109 format: int32
110
114111- `environment_id: string`
115112
116113 ID of the `environment` defining the container configuration for sessions created from this deployment.
117114
115 minLength: 1, maxLength: 128
116
118117- `initial_events: array of BetaManagedAgentsDeploymentInitialEventParams`
119118
120119 Events to send to each session immediately after creation. At least 1, maximum 50.
121120
122 - `BetaManagedAgentsUserMessageEventParams object { content, type }`
121 - `BetaManagedAgentsUserMessageEventParams object`
123122
124123 Parameters for sending a user message to the session.
125124
from line 126
127126
128127 Array of content blocks for the user message.
129128
130 - `BetaManagedAgentsTextBlock object { text, type }`
129 - `BetaManagedAgentsTextBlock object`
131130
132131 Regular text content.
133132
from line 134
135134
136135 The text content.
137136
137 minLength: 1
138
138139 - `type: "text"`
139140
140 - `"text"`
141 - `BetaManagedAgentsImageBlock object`
141142
142 - `BetaManagedAgentsImageBlock object { source, type }`
143
144143 Image content specified directly as base64 data or as a reference via a URL.
145144
146145 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
from line 146
147146
148147 Union type for image source variants.
149148
150 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
149 - `BetaManagedAgentsBase64ImageSource object`
151150
152151 Base64-encoded image data.
153152
from line 154
155154
156155 Base64-encoded image data.
157156
157 minLength: 1
158
158159 - `media_type: string`
159160
160161 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
161162
163 minLength: 1
164
162165 - `type: "base64"`
163166
164 - `"base64"`
167 - `BetaManagedAgentsURLImageSource object`
165168
166 - `BetaManagedAgentsURLImageSource object { type, url }`
167
168169 Image referenced by URL.
169170
170171 - `type: "url"`
171172
172 - `"url"`
173
174173 - `url: string`
175174
176175 URL of the image to fetch.
177176
178 - `BetaManagedAgentsFileImageSource object { file_id, type }`
177 minLength: 1
179178
179 - `BetaManagedAgentsFileImageSource object`
180
180181 Image referenced by file ID.
181182
182183 - `file_id: string`
from line 184
183184
184185 ID of a previously uploaded file.
185186
187 minLength: 1
188
186189 - `type: "file"`
187190
188 - `"file"`
189
190191 - `type: "image"`
191192
192 - `"image"`
193 - `BetaManagedAgentsDocumentBlock object`
193194
194 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
195
196195 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
197196
198197 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
from line 198
199198
200199 Union type for document source variants.
201200
202 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
201 - `BetaManagedAgentsBase64DocumentSource object`
203202
204203 Base64-encoded document data.
205204
from line 206
207206
208207 Base64-encoded document data.
209208
209 minLength: 1
210
210211 - `media_type: string`
211212
212213 MIME type of the document (e.g., "application/pdf").
213214
215 minLength: 1
216
214217 - `type: "base64"`
215218
216 - `"base64"`
219 - `BetaManagedAgentsPlainTextDocumentSource object`
217220
218 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
219
220221 Plain text document content.
221222
222223 - `data: string`
from line 224
223224
224225 The plain text content.
225226
227 minLength: 1
228
226229 - `media_type: "text/plain"`
227230
228231 MIME type of the text content. Must be "text/plain".
229232
230 - `"text/plain"`
231
232233 - `type: "text"`
233234
234 - `"text"`
235 - `BetaManagedAgentsURLDocumentSource object`
235236
236 - `BetaManagedAgentsURLDocumentSource object { type, url }`
237
238237 Document referenced by URL.
239238
240239 - `type: "url"`
241240
242 - `"url"`
243
244241 - `url: string`
245242
246243 URL of the document to fetch.
247244
248 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
245 minLength: 1
249246
247 - `BetaManagedAgentsFileDocumentSource object`
248
250249 Document referenced by file ID.
251250
252251 - `file_id: string`
from line 252
253252
254253 ID of a previously uploaded file.
255254
255 minLength: 1
256
256257 - `type: "file"`
257258
258 - `"file"`
259
260259 - `type: "document"`
261260
262 - `"document"`
263
264261 - `context: optional string or null`
265262
266263 Additional context about the document for the model.
from line 266
269266
270267 The title of the document.
271268
272 - `BetaManagedAgentsRedactedBlock object { type }`
269 - `BetaManagedAgentsRedactedBlock object`
273270
274271 Placeholder for content withheld by Anthropic model policy.
275272
276273 - `type: "redacted"`
277274
278 - `"redacted"`
279
280275 - `type: "user.message"`
281276
282 - `"user.message"`
277 - `BetaManagedAgentsUserDefineOutcomeEventParams object`
283278
284 - `BetaManagedAgentsUserDefineOutcomeEventParams object { description, rubric, type, max_iterations }`
285
286279 Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.
287280
288281 - `description: string`
from line 286
293286
294287 Rubric for grading the quality of an outcome.
295288
296 - `BetaManagedAgentsFileRubricParams object { file_id, type }`
289 - `BetaManagedAgentsFileRubricParams object`
297290
298291 Rubric referenced by a file uploaded via the Files API.
299292
from line 296
303296
304297 - `type: "file"`
305298
306 - `"file"`
299 - `BetaManagedAgentsTextRubricParams object`
307300
308 - `BetaManagedAgentsTextRubricParams object { content, type }`
309
310301 Rubric content provided inline as text.
311302
312303 - `content: string`
from line 304
313304
314305 Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.
315306
307 maxLength: 262144
308
316309 - `type: "text"`
317310
318 - `"text"`
319
320311 - `type: "user.define_outcome"`
321312
322 - `"user.define_outcome"`
323
324313 - `max_iterations: optional number or null`
325314
326315 Eval→revision cycles before giving up. Default 3, max 20.
327316
328 - `BetaManagedAgentsSystemMessageEventParams object { content, type }`
317 format: int32
329318
319 - `BetaManagedAgentsSystemMessageEventParams object`
320
330321 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.
331322
332323 - `content: array of BetaManagedAgentsSystemContentBlock`
from line 328
337328
338329 The text content.
339330
331 minLength: 1
332
340333 - `type: "text"`
341334
342 - `"text"`
343
344335 - `type: "system.message"`
345336
346 - `"system.message"`
347
348337- `name: string`
349338
350339 Human-readable name for the deployment.
351340
341 minLength: 1, maxLength: 256
342
352343- `budget: optional BetaManagedAgentsBudgetLimit or null`
353344
354345 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 356
365356
366357 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.
367358
368 - `"USD"`
369
370359 - `type: "limit"`
371360
372 - `"limit"`
373
374361- `description: optional string or null`
375362
376363 Description of what the deployment does.
377364
365 maxLength: 2048
366
378367- `metadata: optional map[string]`
379368
380369 Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.
from line 372
383372
384373 Resources (e.g. repositories, files) to mount into each session's container. Maximum 500.
385374
386 - `BetaManagedAgentsGitHubRepositoryResourceParams object { authorization_token, type, url, 2 more }`
375 - `BetaManagedAgentsGitHubRepositoryResourceParams object`
387376
388377 Mount a GitHub repository into the session's container.
389378
from line 380
391380
392381 GitHub authorization token used to clone the repository.
393382
383 minLength: 1, maxLength: 4096
384
394385 - `type: "github_repository"`
395386
396 - `"github_repository"`
397
398387 - `url: string`
399388
400389 Github URL of the repository
401390
391 minLength: 1, maxLength: 2048
392
402393 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
403394
404395 Branch or commit to check out. Defaults to the repository's default branch.
405396
406 - `BetaManagedAgentsBranchCheckout object { name, type }`
397 - `BetaManagedAgentsBranchCheckout object`
407398
408399 - `name: string`
409400
410401 Branch name to check out.
411402
403 minLength: 1, maxLength: 255
404
412405 - `type: "branch"`
413406
414 - `"branch"`
407 - `BetaManagedAgentsCommitCheckout object`
415408
416 - `BetaManagedAgentsCommitCheckout object { sha, type }`
417
418409 - `sha: string`
419410
420411 Full commit SHA to check out.
421412
413 minLength: 7, maxLength: 64
414
422415 - `type: "commit"`
423416
424 - `"commit"`
425
426417 - `mount_path: optional string or null`
427418
428419 Mount path in the container. Defaults to `/workspace/<repo-name>`.
429420
430 - `BetaManagedAgentsFileResourceParams object { file_id, type, mount_path }`
421 minLength: 1, maxLength: 4096
431422
423 - `BetaManagedAgentsFileResourceParams object`
424
432425 Mount a file uploaded via the Files API into the session.
433426
434427 - `file_id: string`
from line 428
435428
436429 ID of a previously uploaded file.
437430
431 minLength: 1, maxLength: 128
432
438433 - `type: "file"`
439434
440 - `"file"`
441
442435 - `mount_path: optional string or null`
443436
444437 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
445438
446 - `BetaManagedAgentsMemoryStoreResourceParam object { memory_store_id, type, access, instructions }`
439 minLength: 1, maxLength: 4096
447440
441 - `BetaManagedAgentsMemoryStoreResourceParam object`
442
448443 Parameters for attaching a memory store to an agent session.
449444
450445 - `memory_store_id: string`
from line 448
453448
454449 - `type: "memory_store"`
455450
456 - `"memory_store"`
457
458451 - `access: optional "read_write" or "read_only" or null`
459452
460453 Access mode for an attached memory store.
from line 460
467460
468461 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
469462
463 maxLength: 4096
464
470465- `schedule: optional BetaManagedAgentsScheduleParams or null`
471466
472467 5-field POSIX cron schedule. Literal wall-clock matching in the configured timezone.
from line 470
475470
476471 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).
477472
473 minLength: 1, maxLength: 256
474
478475 - `timezone: string`
479476
480477 Required. IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). Validated against the IANA timezone database.
481478
479 minLength: 1
480
482481 - `type: "cron"`
483482
484 - `"cron"`
485
486483- `vault_ids: optional array of string`
487484
488485 Vault IDs for stored credentials the agent can use during sessions created from this deployment. Maximum 50.
489486
490### Returns
487## Returns
491488
492- `BetaManagedAgentsDeployment object { id, agent, archived_at, 14 more }`
489- `BetaManagedAgentsDeployment object`
493490
494491 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.
495492
from line 502
505502
506503 - `type: "agent"`
507504
508 - `"agent"`
509
510505 - `version: number`
511506
507 format: int32
508
512509 - `archived_at: string or null`
513510
514511 A timestamp in RFC 3339 format
515512
513 format: date-time
514
516515 - `created_at: string`
517516
518517 A timestamp in RFC 3339 format
519518
519 format: date-time
520
520521 - `description: string or null`
521522
522523 Description of what the deployment does.
from line 530
529530
530531 Events sent to each session immediately after creation.
531532
532 - `BetaManagedAgentsDeploymentUserMessageEvent object { content, type }`
533 - `BetaManagedAgentsDeploymentUserMessageEvent object`
533534
534535 A user message sent to the session.
535536
from line 538
537538
538539 Array of content blocks for the user message.
539540
540 - `BetaManagedAgentsTextBlock object { text, type }`
541 - `BetaManagedAgentsTextBlock object`
541542
542543 Regular text content.
543544
from line 546
545546
546547 The text content.
547548
549 minLength: 1
550
548551 - `type: "text"`
549552
550 - `"text"`
553 - `BetaManagedAgentsImageBlock object`
551554
552 - `BetaManagedAgentsImageBlock object { source, type }`
553
554555 Image content specified directly as base64 data or as a reference via a URL.
555556
556557 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
from line 558
557558
558559 Union type for image source variants.
559560
560 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
561 - `BetaManagedAgentsBase64ImageSource object`
561562
562563 Base64-encoded image data.
563564
from line 566
565566
566567 Base64-encoded image data.
567568
569 minLength: 1
570
568571 - `media_type: string`
569572
570573 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
571574
575 minLength: 1
576
572577 - `type: "base64"`
573578
574 - `"base64"`
579 - `BetaManagedAgentsURLImageSource object`
575580
576 - `BetaManagedAgentsURLImageSource object { type, url }`
577
578581 Image referenced by URL.
579582
580583 - `type: "url"`
581584
582 - `"url"`
583
584585 - `url: string`
585586
586587 URL of the image to fetch.
587588
588 - `BetaManagedAgentsFileImageSource object { file_id, type }`
589 minLength: 1
589590
591 - `BetaManagedAgentsFileImageSource object`
592
590593 Image referenced by file ID.
591594
592595 - `file_id: string`
from line 596
593596
594597 ID of a previously uploaded file.
595598
599 minLength: 1
600
596601 - `type: "file"`
597602
598 - `"file"`
599
600603 - `type: "image"`
601604
602 - `"image"`
605 - `BetaManagedAgentsDocumentBlock object`
603606
604 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
605
606607 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
607608
608609 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
from line 610
609610
610611 Union type for document source variants.
611612
612 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
613 - `BetaManagedAgentsBase64DocumentSource object`
613614
614615 Base64-encoded document data.
615616
from line 618
617618
618619 Base64-encoded document data.
619620
621 minLength: 1
622
620623 - `media_type: string`
621624
622625 MIME type of the document (e.g., "application/pdf").
623626
627 minLength: 1
628
624629 - `type: "base64"`
625630
626 - `"base64"`
631 - `BetaManagedAgentsPlainTextDocumentSource object`
627632
628 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
629
630633 Plain text document content.
631634
632635 - `data: string`
from line 636
633636
634637 The plain text content.
635638
639 minLength: 1
640
636641 - `media_type: "text/plain"`
637642
638643 MIME type of the text content. Must be "text/plain".
639644
640 - `"text/plain"`
641
642645 - `type: "text"`
643646
644 - `"text"`
647 - `BetaManagedAgentsURLDocumentSource object`
645648
646 - `BetaManagedAgentsURLDocumentSource object { type, url }`
647
648649 Document referenced by URL.
649650
650651 - `type: "url"`
651652
652 - `"url"`
653
654653 - `url: string`
655654
656655 URL of the document to fetch.
657656
658 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
657 minLength: 1
659658
659 - `BetaManagedAgentsFileDocumentSource object`
660
660661 Document referenced by file ID.
661662
662663 - `file_id: string`
from line 664
663664
664665 ID of a previously uploaded file.
665666
667 minLength: 1
668
666669 - `type: "file"`
667670
668 - `"file"`
669
670671 - `type: "document"`
671672
672 - `"document"`
673
674673 - `context: optional string or null`
675674
676675 Additional context about the document for the model.
from line 678
679678
680679 The title of the document.
681680
682 - `BetaManagedAgentsRedactedBlock object { type }`
681 - `BetaManagedAgentsRedactedBlock object`
683682
684683 Placeholder for content withheld by Anthropic model policy.
685684
686685 - `type: "redacted"`
687686
688 - `"redacted"`
689
690687 - `type: "user.message"`
691688
692 - `"user.message"`
689 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`
693690
694 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object { description, rubric, type, max_iterations }`
695
696691 An outcome the agent should work toward. The agent begins work on receipt.
697692
698693 - `description: string`
from line 698
703698
704699 Rubric for grading the quality of an outcome.
705700
706 - `BetaManagedAgentsFileRubric object { file_id, type }`
701 - `BetaManagedAgentsFileRubric object`
707702
708703 Rubric referenced by a file uploaded via the Files API.
709704
from line 708
713708
714709 - `type: "file"`
715710
716 - `"file"`
711 - `BetaManagedAgentsTextRubric object`
717712
718 - `BetaManagedAgentsTextRubric object { content, type }`
719
720713 Rubric content provided inline as text.
721714
722715 - `content: string`
from line 718
725718
726719 - `type: "text"`
727720
728 - `"text"`
729
730721 - `type: "user.define_outcome"`
731722
732 - `"user.define_outcome"`
733
734723 - `max_iterations: optional number or null`
735724
736725 Eval→revision cycles before giving up. Default 3, max 20.
737726
738 - `BetaManagedAgentsDeploymentSystemMessageEvent object { content, type }`
727 format: int32
739728
729 - `BetaManagedAgentsDeploymentSystemMessageEvent object`
730
740731 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.
741732
742733 - `content: array of BetaManagedAgentsSystemContentBlock`
from line 738
747738
748739 The text content.
749740
741 minLength: 1
742
750743 - `type: "text"`
751744
752 - `"text"`
753
754745 - `type: "system.message"`
755746
756 - `"system.message"`
757
758747 - `metadata: map[string]`
759748
760749 Arbitrary key-value metadata. Maximum 16 pairs.
from line 756
767756
768757 Why a deployment is paused. Non-null exactly when `status` is `paused`.
769758
770 - `BetaManagedAgentsManualDeploymentPausedReason object { type }`
759 - `BetaManagedAgentsManualDeploymentPausedReason object`
771760
772761 The caller invoked the pause endpoint on the deployment.
773762
774763 - `type: "manual"`
775764
776 - `"manual"`
765 - `BetaManagedAgentsErrorDeploymentPausedReason object`
777766
778 - `BetaManagedAgentsErrorDeploymentPausedReason object { error, type }`
779
780767 A scheduled fire recorded a failed run whose error auto-pauses the deployment.
781768
782769 - `error: BetaManagedAgentsDeploymentPausedReasonError`
from line 770
783770
784771 The error that triggered an auto-pause. Matches the failed run's `error.type`.
785772
786 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object { type }`
773 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object`
787774
788775 The deployment's environment was archived.
789776
790777 - `type: "environment_archived_error"`
791778
792 - `"environment_archived_error"`
779 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object`
793780
794 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object { type }`
795
796781 The deployment's agent was archived.
797782
798783 - `type: "agent_archived_error"`
799784
800 - `"agent_archived_error"`
785 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object`
801786
802 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object { type }`
803
804787 The deployment's environment no longer exists.
805788
806789 - `type: "environment_not_found_error"`
807790
808 - `"environment_not_found_error"`
791 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object`
809792
810 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object { type }`
811
812793 A vault referenced by the deployment no longer exists.
813794
814795 - `type: "vault_not_found_error"`
815796
816 - `"vault_not_found_error"`
797 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object`
817798
818 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object { type }`
819
820799 A file resource referenced by the deployment no longer exists.
821800
822801 - `type: "file_not_found_error"`
823802
824 - `"file_not_found_error"`
803 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object`
825804
826 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object { type }`
827
828805 A referenced resource no longer exists and its kind was not reported.
829806
830807 - `type: "session_resource_not_found_error"`
831808
832 - `"session_resource_not_found_error"`
809 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object`
833810
834 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object { type }`
835
836811 The deployment's workspace was archived.
837812
838813 - `type: "workspace_archived_error"`
839814
840 - `"workspace_archived_error"`
815 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object`
841816
842 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object { type }`
843
844817 The deployment's organization is disabled.
845818
846819 - `type: "organization_disabled_error"`
847820
848 - `"organization_disabled_error"`
821 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object`
849822
850 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object { type }`
851
852823 A memory store referenced by the deployment is archived.
853824
854825 - `type: "memory_store_archived_error"`
855826
856 - `"memory_store_archived_error"`
827 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object`
857828
858 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object { type }`
859
860829 A skill referenced by the deployment's agent no longer exists.
861830
862831 - `type: "skill_not_found_error"`
863832
864 - `"skill_not_found_error"`
833 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object`
865834
866 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object { type }`
867
868835 A vault referenced by the deployment is archived.
869836
870837 - `type: "vault_archived_error"`
871838
872 - `"vault_archived_error"`
839 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object`
873840
874 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object { type }`
875
876841 An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.
877842
878843 - `type: "unknown_error"`
879844
880 - `"unknown_error"`
845 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object`
881846
882 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object { type }`
883
884847 The deployment configures resources, but its environment is self-hosted and cannot mount them.
885848
886849 - `type: "self_hosted_resources_unsupported_error"`
887850
888 - `"self_hosted_resources_unsupported_error"`
851 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object`
889852
890 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object { type }`
891
892853 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
893854
894855 - `type: "mcp_egress_blocked_error"`
895856
896 - `"mcp_egress_blocked_error"`
897
898857 - `type: "error"`
899858
900 - `"error"`
901
902859 - `resources: array of BetaManagedAgentsSessionResourceConfig`
903860
904861 Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.
905862
906 - `BetaManagedAgentsGitHubRepositoryResourceConfig object { type, url, checkout, mount_path }`
863 - `BetaManagedAgentsGitHubRepositoryResourceConfig object`
907864
908865 A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.
909866
910867 - `type: "github_repository"`
911868
912 - `"github_repository"`
913
914869 - `url: string`
915870
916871 Github URL of the repository
from line 874
919874
920875 Branch or commit to check out. Defaults to the repository's default branch.
921876
922 - `BetaManagedAgentsBranchCheckout object { name, type }`
877 - `BetaManagedAgentsBranchCheckout object`
923878
924879 - `name: string`
925880
926881 Branch name to check out.
927882
883 minLength: 1, maxLength: 255
884
928885 - `type: "branch"`
929886
930 - `"branch"`
887 - `BetaManagedAgentsCommitCheckout object`
931888
932 - `BetaManagedAgentsCommitCheckout object { sha, type }`
933
934889 - `sha: string`
935890
936891 Full commit SHA to check out.
937892
893 minLength: 7, maxLength: 64
894
938895 - `type: "commit"`
939896
940 - `"commit"`
941
942897 - `mount_path: optional string or null`
943898
944899 Mount path in the container. Defaults to `/workspace/<repo-name>`.
945900
946 - `BetaManagedAgentsFileResourceConfig object { file_id, type, mount_path }`
901 - `BetaManagedAgentsFileResourceConfig object`
947902
948903 A file mounted into each session's container.
949904
from line 908
953908
954909 - `type: "file"`
955910
956 - `"file"`
957
958911 - `mount_path: optional string or null`
959912
960913 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
961914
962 - `BetaManagedAgentsMemoryStoreResourceConfig object { memory_store_id, type, access, instructions }`
915 - `BetaManagedAgentsMemoryStoreResourceConfig object`
963916
964917 A memory store attached to each session created from this deployment.
965918
from line 922
969922
970923 - `type: "memory_store"`
971924
972 - `"memory_store"`
973
974925 - `access: optional "read_write" or "read_only" or null`
975926
976927 Access mode for an attached memory store.
from line 942
991942
992943 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).
993944
945 minLength: 1, maxLength: 256
946
994947 - `timezone: string`
995948
996949 IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").
997950
951 minLength: 1
952
998953 - `type: "cron"`
999954
1000 - `"cron"`
1001
1002955 - `last_run_at: optional string or null`
1003956
1004957 A timestamp in RFC 3339 format
1005958
959 format: date-time
960
1006961 - `upcoming_runs_at: optional array of string`
1007962
1008963 Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.
from line 972
1017972
1018973 - `type: "deployment"`
1019974
1020 - `"deployment"`
1021
1022975 - `updated_at: string`
1023976
1024977 A timestamp in RFC 3339 format
1025978
979 format: date-time
980
1026981 - `vault_ids: array of string`
1027982
1028983 Vault IDs supplying stored credentials for sessions created from this deployment.
from line 998
1043998
1044999 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.
10451000
1046 - `"USD"`
1047
10481001 - `type: "limit"`
10491002
1050 - `"limit"`
1003## Example
10511004
1052### Example
1053
1054```http
1005```bash
10551006curl https://api.anthropic.com/v1/deployments \
10561007 -H 'Content-Type: application/json' \
10571008 -H 'anthropic-version: 2023-06-01' \
from line 1026
10751026 }'
10761027```
10771028
1078#### Response
1029### Response (200)
10791030
10801031```json
10811032{
api/beta/deployments/list Changed · +95 / -140 lines
# List Deployments ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List Deployments ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: List Deployments
3url: https://platform.claude.com/docs/en/api/beta/deployments/list
4---
1# List Deployments
52
6## List Deployments
3**GET** `/v1/deployments`
74
8**get** `/v1/deployments`
9
105List Deployments
116
12### Query Parameters
7## Query parameters
138
149- `agent_id: optional string`
1510
from line 14
1914
2015 Return deployments created at or after this time (inclusive).
2116
17 format: date-time
18
2219- `"created_at[lte]": optional string`
2320
2421 Return deployments created at or before this time (inclusive).
2522
23 format: date-time
24
2625- `include_archived: optional boolean`
2726
2827 When true, includes archived deployments. Default: false (exclude archived).
from line 30
3130
3231 Maximum results per page. Default 20, maximum 100.
3332
33 format: int32
34
3435- `page: optional string`
3536
3637 Opaque pagination cursor.
from line 44
4344
4445 - `"paused"`
4546
46### Header Parameters
47## Headers
4748
4849- `"anthropic-beta": optional array of AnthropicBeta`
4950
from line 122
121122
122123 - `"mid-conversation-tool-changes-2026-07-01"`
123124
124### Returns
125## Returns
125126
126127- `data: array of BetaManagedAgentsDeployment`
127128
from line 140
139140
140141 - `type: "agent"`
141142
142 - `"agent"`
143
144143 - `version: number`
145144
145 format: int32
146
146147 - `archived_at: string or null`
147148
148149 A timestamp in RFC 3339 format
149150
151 format: date-time
152
150153 - `created_at: string`
151154
152155 A timestamp in RFC 3339 format
153156
157 format: date-time
158
154159 - `description: string or null`
155160
156161 Description of what the deployment does.
from line 168
163168
164169 Events sent to each session immediately after creation.
165170
166 - `BetaManagedAgentsDeploymentUserMessageEvent object { content, type }`
171 - `BetaManagedAgentsDeploymentUserMessageEvent object`
167172
168173 A user message sent to the session.
169174
from line 176
171176
172177 Array of content blocks for the user message.
173178
174 - `BetaManagedAgentsTextBlock object { text, type }`
179 - `BetaManagedAgentsTextBlock object`
175180
176181 Regular text content.
177182
from line 184
179184
180185 The text content.
181186
187 minLength: 1
188
182189 - `type: "text"`
183190
184 - `"text"`
191 - `BetaManagedAgentsImageBlock object`
185192
186 - `BetaManagedAgentsImageBlock object { source, type }`
187
188193 Image content specified directly as base64 data or as a reference via a URL.
189194
190195 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
from line 196
191196
192197 Union type for image source variants.
193198
194 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
199 - `BetaManagedAgentsBase64ImageSource object`
195200
196201 Base64-encoded image data.
197202
from line 204
199204
200205 Base64-encoded image data.
201206
207 minLength: 1
208
202209 - `media_type: string`
203210
204211 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
205212
213 minLength: 1
214
206215 - `type: "base64"`
207216
208 - `"base64"`
217 - `BetaManagedAgentsURLImageSource object`
209218
210 - `BetaManagedAgentsURLImageSource object { type, url }`
211
212219 Image referenced by URL.
213220
214221 - `type: "url"`
215222
216 - `"url"`
217
218223 - `url: string`
219224
220225 URL of the image to fetch.
221226
222 - `BetaManagedAgentsFileImageSource object { file_id, type }`
227 minLength: 1
223228
229 - `BetaManagedAgentsFileImageSource object`
230
224231 Image referenced by file ID.
225232
226233 - `file_id: string`
from line 234
227234
228235 ID of a previously uploaded file.
229236
237 minLength: 1
238
230239 - `type: "file"`
231240
232 - `"file"`
233
234241 - `type: "image"`
235242
236 - `"image"`
243 - `BetaManagedAgentsDocumentBlock object`
237244
238 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
239
240245 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
241246
242247 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
from line 248
243248
244249 Union type for document source variants.
245250
246 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
251 - `BetaManagedAgentsBase64DocumentSource object`
247252
248253 Base64-encoded document data.
249254
from line 256
251256
252257 Base64-encoded document data.
253258
259 minLength: 1
260
254261 - `media_type: string`
255262
256263 MIME type of the document (e.g., "application/pdf").
257264
265 minLength: 1
266
258267 - `type: "base64"`
259268
260 - `"base64"`
269 - `BetaManagedAgentsPlainTextDocumentSource object`
261270
262 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
263
264271 Plain text document content.
265272
266273 - `data: string`
from line 274
267274
268275 The plain text content.
269276
277 minLength: 1
278
270279 - `media_type: "text/plain"`
271280
272281 MIME type of the text content. Must be "text/plain".
273282
274 - `"text/plain"`
275
276283 - `type: "text"`
277284
278 - `"text"`
285 - `BetaManagedAgentsURLDocumentSource object`
279286
280 - `BetaManagedAgentsURLDocumentSource object { type, url }`
281
282287 Document referenced by URL.
283288
284289 - `type: "url"`
285290
286 - `"url"`
287
288291 - `url: string`
289292
290293 URL of the document to fetch.
291294
292 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
295 minLength: 1
293296
297 - `BetaManagedAgentsFileDocumentSource object`
298
294299 Document referenced by file ID.
295300
296301 - `file_id: string`
from line 302
297302
298303 ID of a previously uploaded file.
299304
305 minLength: 1
306
300307 - `type: "file"`
301308
302 - `"file"`
303
304309 - `type: "document"`
305310
306 - `"document"`
307
308311 - `context: optional string or null`
309312
310313 Additional context about the document for the model.
from line 316
313316
314317 The title of the document.
315318
316 - `BetaManagedAgentsRedactedBlock object { type }`
319 - `BetaManagedAgentsRedactedBlock object`
317320
318321 Placeholder for content withheld by Anthropic model policy.
319322
320323 - `type: "redacted"`
321324
322 - `"redacted"`
323
324325 - `type: "user.message"`
325326
326 - `"user.message"`
327 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`
327328
328 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object { description, rubric, type, max_iterations }`
329
330329 An outcome the agent should work toward. The agent begins work on receipt.
331330
332331 - `description: string`
from line 336
337336
338337 Rubric for grading the quality of an outcome.
339338
340 - `BetaManagedAgentsFileRubric object { file_id, type }`
339 - `BetaManagedAgentsFileRubric object`
341340
342341 Rubric referenced by a file uploaded via the Files API.
343342
from line 346
347346
348347 - `type: "file"`
349348
350 - `"file"`
349 - `BetaManagedAgentsTextRubric object`
351350
352 - `BetaManagedAgentsTextRubric object { content, type }`
353
354351 Rubric content provided inline as text.
355352
356353 - `content: string`
from line 356
359356
360357 - `type: "text"`
361358
362 - `"text"`
363
364359 - `type: "user.define_outcome"`
365360
366 - `"user.define_outcome"`
367
368361 - `max_iterations: optional number or null`
369362
370363 Eval→revision cycles before giving up. Default 3, max 20.
371364
372 - `BetaManagedAgentsDeploymentSystemMessageEvent object { content, type }`
365 format: int32
373366
367 - `BetaManagedAgentsDeploymentSystemMessageEvent object`
368
374369 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.
375370
376371 - `content: array of BetaManagedAgentsSystemContentBlock`
from line 376
381376
382377 The text content.
383378
379 minLength: 1
380
384381 - `type: "text"`
385382
386 - `"text"`
387
388383 - `type: "system.message"`
389384
390 - `"system.message"`
391
392385 - `metadata: map[string]`
393386
394387 Arbitrary key-value metadata. Maximum 16 pairs.
from line 394
401394
402395 Why a deployment is paused. Non-null exactly when `status` is `paused`.
403396
404 - `BetaManagedAgentsManualDeploymentPausedReason object { type }`
397 - `BetaManagedAgentsManualDeploymentPausedReason object`
405398
406399 The caller invoked the pause endpoint on the deployment.
407400
408401 - `type: "manual"`
409402
410 - `"manual"`
403 - `BetaManagedAgentsErrorDeploymentPausedReason object`
411404
412 - `BetaManagedAgentsErrorDeploymentPausedReason object { error, type }`
413
414405 A scheduled fire recorded a failed run whose error auto-pauses the deployment.
415406
416407 - `error: BetaManagedAgentsDeploymentPausedReasonError`
from line 408
417408
418409 The error that triggered an auto-pause. Matches the failed run's `error.type`.
419410
420 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object { type }`
411 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object`
421412
422413 The deployment's environment was archived.
423414
424415 - `type: "environment_archived_error"`
425416
426 - `"environment_archived_error"`
417 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object`
427418
428 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object { type }`
429
430419 The deployment's agent was archived.
431420
432421 - `type: "agent_archived_error"`
433422
434 - `"agent_archived_error"`
423 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object`
435424
436 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object { type }`
437
438425 The deployment's environment no longer exists.
439426
440427 - `type: "environment_not_found_error"`
441428
442 - `"environment_not_found_error"`
429 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object`
443430
444 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object { type }`
445
446431 A vault referenced by the deployment no longer exists.
447432
448433 - `type: "vault_not_found_error"`
449434
450 - `"vault_not_found_error"`
435 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object`
451436
452 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object { type }`
453
454437 A file resource referenced by the deployment no longer exists.
455438
456439 - `type: "file_not_found_error"`
457440
458 - `"file_not_found_error"`
441 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object`
459442
460 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object { type }`
461
462443 A referenced resource no longer exists and its kind was not reported.
463444
464445 - `type: "session_resource_not_found_error"`
465446
466 - `"session_resource_not_found_error"`
447 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object`
467448
468 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object { type }`
469
470449 The deployment's workspace was archived.
471450
472451 - `type: "workspace_archived_error"`
473452
474 - `"workspace_archived_error"`
453 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object`
475454
476 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object { type }`
477
478455 The deployment's organization is disabled.
479456
480457 - `type: "organization_disabled_error"`
481458
482 - `"organization_disabled_error"`
459 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object`
483460
484 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object { type }`
485
486461 A memory store referenced by the deployment is archived.
487462
488463 - `type: "memory_store_archived_error"`
489464
490 - `"memory_store_archived_error"`
465 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object`
491466
492 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object { type }`
493
494467 A skill referenced by the deployment's agent no longer exists.
495468
496469 - `type: "skill_not_found_error"`
497470
498 - `"skill_not_found_error"`
471 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object`
499472
500 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object { type }`
501
502473 A vault referenced by the deployment is archived.
503474
504475 - `type: "vault_archived_error"`
505476
506 - `"vault_archived_error"`
477 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object`
507478
508 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object { type }`
509
510479 An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.
511480
512481 - `type: "unknown_error"`
513482
514 - `"unknown_error"`
483 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object`
515484
516 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object { type }`
517
518485 The deployment configures resources, but its environment is self-hosted and cannot mount them.
519486
520487 - `type: "self_hosted_resources_unsupported_error"`
521488
522 - `"self_hosted_resources_unsupported_error"`
489 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object`
523490
524 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object { type }`
525
526491 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
527492
528493 - `type: "mcp_egress_blocked_error"`
529494
530 - `"mcp_egress_blocked_error"`
531
532495 - `type: "error"`
533496
534 - `"error"`
535
536497 - `resources: array of BetaManagedAgentsSessionResourceConfig`
537498
538499 Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.
539500
540 - `BetaManagedAgentsGitHubRepositoryResourceConfig object { type, url, checkout, mount_path }`
501 - `BetaManagedAgentsGitHubRepositoryResourceConfig object`
541502
542503 A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.
543504
544505 - `type: "github_repository"`
545506
546 - `"github_repository"`
547
548507 - `url: string`
549508
550509 Github URL of the repository
from line 512
553512
554513 Branch or commit to check out. Defaults to the repository's default branch.
555514
556 - `BetaManagedAgentsBranchCheckout object { name, type }`
515 - `BetaManagedAgentsBranchCheckout object`
557516
558517 - `name: string`
559518
560519 Branch name to check out.
561520
521 minLength: 1, maxLength: 255
522
562523 - `type: "branch"`
563524
564 - `"branch"`
525 - `BetaManagedAgentsCommitCheckout object`
565526
566 - `BetaManagedAgentsCommitCheckout object { sha, type }`
567
568527 - `sha: string`
569528
570529 Full commit SHA to check out.
571530
531 minLength: 7, maxLength: 64
532
572533 - `type: "commit"`
573534
574 - `"commit"`
575
576535 - `mount_path: optional string or null`
577536
578537 Mount path in the container. Defaults to `/workspace/<repo-name>`.
579538
580 - `BetaManagedAgentsFileResourceConfig object { file_id, type, mount_path }`
539 - `BetaManagedAgentsFileResourceConfig object`
581540
582541 A file mounted into each session's container.
583542
from line 546
587546
588547 - `type: "file"`
589548
590 - `"file"`
591
592549 - `mount_path: optional string or null`
593550
594551 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
595552
596 - `BetaManagedAgentsMemoryStoreResourceConfig object { memory_store_id, type, access, instructions }`
553 - `BetaManagedAgentsMemoryStoreResourceConfig object`
597554
598555 A memory store attached to each session created from this deployment.
599556
from line 560
603560
604561 - `type: "memory_store"`
605562
606 - `"memory_store"`
607
608563 - `access: optional "read_write" or "read_only" or null`
609564
610565 Access mode for an attached memory store.
from line 580
625580
626581 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).
627582
583 minLength: 1, maxLength: 256
584
628585 - `timezone: string`
629586
630587 IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").
631588
589 minLength: 1
590
632591 - `type: "cron"`
633592
634 - `"cron"`
635
636593 - `last_run_at: optional string or null`
637594
638595 A timestamp in RFC 3339 format
639596
597 format: date-time
598
640599 - `upcoming_runs_at: optional array of string`
641600
642601 Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.
from line 610
651610
652611 - `type: "deployment"`
653612
654 - `"deployment"`
655
656613 - `updated_at: string`
657614
658615 A timestamp in RFC 3339 format
659616
617 format: date-time
618
660619 - `vault_ids: array of string`
661620
662621 Vault IDs supplying stored credentials for sessions created from this deployment.
from line 636
677636
678637 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.
679638
680 - `"USD"`
681
682639 - `type: "limit"`
683640
684 - `"limit"`
685
686641- `next_page: optional string or null`
687642
688643 Opaque cursor for the next page. Null when no more results.
689644
690### Example
645## Example
691646
692```http
647```bash
693648curl https://api.anthropic.com/v1/deployments \
694649 -H 'anthropic-version: 2023-06-01' \
695650 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 651
696651 -H "X-Api-Key: $ANTHROPIC_API_KEY"
697652```
698653
699#### Response
654### Response (200)
700655
701656```json
702657{
api/beta/deployments/pause Changed · +91 / -142 lines
# Pause Deployment ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Pause Deployment ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Pause Deployment
3url: https://platform.claude.com/docs/en/api/beta/deployments/pause
4---
1# Pause Deployment
52
6## Pause Deployment
3**POST** `/v1/deployments/{deployment_id}/pause`
74
8**post** `/v1/deployments/{deployment_id}/pause`
9
105Pause Deployment
116
12### Path Parameters
7## Path parameters
138
149- `deployment_id: string`
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Returns
89## Returns
9590
96- `BetaManagedAgentsDeployment object { id, agent, archived_at, 14 more }`
91- `BetaManagedAgentsDeployment object`
9792
9893 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.
9994
from line 104
109104
110105 - `type: "agent"`
111106
112 - `"agent"`
113
114107 - `version: number`
115108
109 format: int32
110
116111 - `archived_at: string or null`
117112
118113 A timestamp in RFC 3339 format
119114
115 format: date-time
116
120117 - `created_at: string`
121118
122119 A timestamp in RFC 3339 format
123120
121 format: date-time
122
124123 - `description: string or null`
125124
126125 Description of what the deployment does.
from line 132
133132
134133 Events sent to each session immediately after creation.
135134
136 - `BetaManagedAgentsDeploymentUserMessageEvent object { content, type }`
135 - `BetaManagedAgentsDeploymentUserMessageEvent object`
137136
138137 A user message sent to the session.
139138
from line 140
141140
142141 Array of content blocks for the user message.
143142
144 - `BetaManagedAgentsTextBlock object { text, type }`
143 - `BetaManagedAgentsTextBlock object`
145144
146145 Regular text content.
147146
from line 148
149148
150149 The text content.
151150
151 minLength: 1
152
152153 - `type: "text"`
153154
154 - `"text"`
155 - `BetaManagedAgentsImageBlock object`
155156
156 - `BetaManagedAgentsImageBlock object { source, type }`
157
158157 Image content specified directly as base64 data or as a reference via a URL.
159158
160159 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
from line 160
161160
162161 Union type for image source variants.
163162
164 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
163 - `BetaManagedAgentsBase64ImageSource object`
165164
166165 Base64-encoded image data.
167166
from line 168
169168
170169 Base64-encoded image data.
171170
171 minLength: 1
172
172173 - `media_type: string`
173174
174175 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
175176
177 minLength: 1
178
176179 - `type: "base64"`
177180
178 - `"base64"`
181 - `BetaManagedAgentsURLImageSource object`
179182
180 - `BetaManagedAgentsURLImageSource object { type, url }`
181
182183 Image referenced by URL.
183184
184185 - `type: "url"`
185186
186 - `"url"`
187
188187 - `url: string`
189188
190189 URL of the image to fetch.
191190
192 - `BetaManagedAgentsFileImageSource object { file_id, type }`
191 minLength: 1
193192
193 - `BetaManagedAgentsFileImageSource object`
194
194195 Image referenced by file ID.
195196
196197 - `file_id: string`
from line 198
197198
198199 ID of a previously uploaded file.
199200
201 minLength: 1
202
200203 - `type: "file"`
201204
202 - `"file"`
203
204205 - `type: "image"`
205206
206 - `"image"`
207 - `BetaManagedAgentsDocumentBlock object`
207208
208 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
209
210209 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
211210
212211 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
from line 212
213212
214213 Union type for document source variants.
215214
216 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
215 - `BetaManagedAgentsBase64DocumentSource object`
217216
218217 Base64-encoded document data.
219218
from line 220
221220
222221 Base64-encoded document data.
223222
223 minLength: 1
224
224225 - `media_type: string`
225226
226227 MIME type of the document (e.g., "application/pdf").
227228
229 minLength: 1
230
228231 - `type: "base64"`
229232
230 - `"base64"`
233 - `BetaManagedAgentsPlainTextDocumentSource object`
231234
232 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
233
234235 Plain text document content.
235236
236237 - `data: string`
from line 238
237238
238239 The plain text content.
239240
241 minLength: 1
242
240243 - `media_type: "text/plain"`
241244
242245 MIME type of the text content. Must be "text/plain".
243246
244 - `"text/plain"`
245
246247 - `type: "text"`
247248
248 - `"text"`
249 - `BetaManagedAgentsURLDocumentSource object`
249250
250 - `BetaManagedAgentsURLDocumentSource object { type, url }`
251
252251 Document referenced by URL.
253252
254253 - `type: "url"`
255254
256 - `"url"`
257
258255 - `url: string`
259256
260257 URL of the document to fetch.
261258
262 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
259 minLength: 1
263260
261 - `BetaManagedAgentsFileDocumentSource object`
262
264263 Document referenced by file ID.
265264
266265 - `file_id: string`
from line 266
267266
268267 ID of a previously uploaded file.
269268
269 minLength: 1
270
270271 - `type: "file"`
271272
272 - `"file"`
273
274273 - `type: "document"`
275274
276 - `"document"`
277
278275 - `context: optional string or null`
279276
280277 Additional context about the document for the model.
from line 280
283280
284281 The title of the document.
285282
286 - `BetaManagedAgentsRedactedBlock object { type }`
283 - `BetaManagedAgentsRedactedBlock object`
287284
288285 Placeholder for content withheld by Anthropic model policy.
289286
290287 - `type: "redacted"`
291288
292 - `"redacted"`
293
294289 - `type: "user.message"`
295290
296 - `"user.message"`
291 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`
297292
298 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object { description, rubric, type, max_iterations }`
299
300293 An outcome the agent should work toward. The agent begins work on receipt.
301294
302295 - `description: string`
from line 300
307300
308301 Rubric for grading the quality of an outcome.
309302
310 - `BetaManagedAgentsFileRubric object { file_id, type }`
303 - `BetaManagedAgentsFileRubric object`
311304
312305 Rubric referenced by a file uploaded via the Files API.
313306
from line 310
317310
318311 - `type: "file"`
319312
320 - `"file"`
313 - `BetaManagedAgentsTextRubric object`
321314
322 - `BetaManagedAgentsTextRubric object { content, type }`
323
324315 Rubric content provided inline as text.
325316
326317 - `content: string`
from line 320
329320
330321 - `type: "text"`
331322
332 - `"text"`
333
334323 - `type: "user.define_outcome"`
335324
336 - `"user.define_outcome"`
337
338325 - `max_iterations: optional number or null`
339326
340327 Eval→revision cycles before giving up. Default 3, max 20.
341328
342 - `BetaManagedAgentsDeploymentSystemMessageEvent object { content, type }`
329 format: int32
343330
331 - `BetaManagedAgentsDeploymentSystemMessageEvent object`
332
344333 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.
345334
346335 - `content: array of BetaManagedAgentsSystemContentBlock`
from line 340
351340
352341 The text content.
353342
343 minLength: 1
344
354345 - `type: "text"`
355346
356 - `"text"`
357
358347 - `type: "system.message"`
359348
360 - `"system.message"`
361
362349 - `metadata: map[string]`
363350
364351 Arbitrary key-value metadata. Maximum 16 pairs.
from line 358
371358
372359 Why a deployment is paused. Non-null exactly when `status` is `paused`.
373360
374 - `BetaManagedAgentsManualDeploymentPausedReason object { type }`
361 - `BetaManagedAgentsManualDeploymentPausedReason object`
375362
376363 The caller invoked the pause endpoint on the deployment.
377364
378365 - `type: "manual"`
379366
380 - `"manual"`
367 - `BetaManagedAgentsErrorDeploymentPausedReason object`
381368
382 - `BetaManagedAgentsErrorDeploymentPausedReason object { error, type }`
383
384369 A scheduled fire recorded a failed run whose error auto-pauses the deployment.
385370
386371 - `error: BetaManagedAgentsDeploymentPausedReasonError`
from line 372
387372
388373 The error that triggered an auto-pause. Matches the failed run's `error.type`.
389374
390 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object { type }`
375 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object`
391376
392377 The deployment's environment was archived.
393378
394379 - `type: "environment_archived_error"`
395380
396 - `"environment_archived_error"`
381 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object`
397382
398 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object { type }`
399
400383 The deployment's agent was archived.
401384
402385 - `type: "agent_archived_error"`
403386
404 - `"agent_archived_error"`
387 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object`
405388
406 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object { type }`
407
408389 The deployment's environment no longer exists.
409390
410391 - `type: "environment_not_found_error"`
411392
412 - `"environment_not_found_error"`
393 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object`
413394
414 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object { type }`
415
416395 A vault referenced by the deployment no longer exists.
417396
418397 - `type: "vault_not_found_error"`
419398
420 - `"vault_not_found_error"`
399 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object`
421400
422 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object { type }`
423
424401 A file resource referenced by the deployment no longer exists.
425402
426403 - `type: "file_not_found_error"`
427404
428 - `"file_not_found_error"`
405 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object`
429406
430 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object { type }`
431
432407 A referenced resource no longer exists and its kind was not reported.
433408
434409 - `type: "session_resource_not_found_error"`
435410
436 - `"session_resource_not_found_error"`
411 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object`
437412
438 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object { type }`
439
440413 The deployment's workspace was archived.
441414
442415 - `type: "workspace_archived_error"`
443416
444 - `"workspace_archived_error"`
417 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object`
445418
446 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object { type }`
447
448419 The deployment's organization is disabled.
449420
450421 - `type: "organization_disabled_error"`
451422
452 - `"organization_disabled_error"`
423 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object`
453424
454 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object { type }`
455
456425 A memory store referenced by the deployment is archived.
457426
458427 - `type: "memory_store_archived_error"`
459428
460 - `"memory_store_archived_error"`
429 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object`
461430
462 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object { type }`
463
464431 A skill referenced by the deployment's agent no longer exists.
465432
466433 - `type: "skill_not_found_error"`
467434
468 - `"skill_not_found_error"`
435 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object`
469436
470 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object { type }`
471
472437 A vault referenced by the deployment is archived.
473438
474439 - `type: "vault_archived_error"`
475440
476 - `"vault_archived_error"`
441 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object`
477442
478 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object { type }`
479
480443 An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.
481444
482445 - `type: "unknown_error"`
483446
484 - `"unknown_error"`
447 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object`
485448
486 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object { type }`
487
488449 The deployment configures resources, but its environment is self-hosted and cannot mount them.
489450
490451 - `type: "self_hosted_resources_unsupported_error"`
491452
492 - `"self_hosted_resources_unsupported_error"`
453 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object`
493454
494 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object { type }`
495
496455 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
497456
498457 - `type: "mcp_egress_blocked_error"`
499458
500 - `"mcp_egress_blocked_error"`
501
502459 - `type: "error"`
503460
504 - `"error"`
505
506461 - `resources: array of BetaManagedAgentsSessionResourceConfig`
507462
508463 Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.
509464
510 - `BetaManagedAgentsGitHubRepositoryResourceConfig object { type, url, checkout, mount_path }`
465 - `BetaManagedAgentsGitHubRepositoryResourceConfig object`
511466
512467 A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.
513468
514469 - `type: "github_repository"`
515470
516 - `"github_repository"`
517
518471 - `url: string`
519472
520473 Github URL of the repository
from line 476
523476
524477 Branch or commit to check out. Defaults to the repository's default branch.
525478
526 - `BetaManagedAgentsBranchCheckout object { name, type }`
479 - `BetaManagedAgentsBranchCheckout object`
527480
528481 - `name: string`
529482
530483 Branch name to check out.
531484
485 minLength: 1, maxLength: 255
486
532487 - `type: "branch"`
533488
534 - `"branch"`
489 - `BetaManagedAgentsCommitCheckout object`
535490
536 - `BetaManagedAgentsCommitCheckout object { sha, type }`
537
538491 - `sha: string`
539492
540493 Full commit SHA to check out.
541494
495 minLength: 7, maxLength: 64
496
542497 - `type: "commit"`
543498
544 - `"commit"`
545
546499 - `mount_path: optional string or null`
547500
548501 Mount path in the container. Defaults to `/workspace/<repo-name>`.
549502
550 - `BetaManagedAgentsFileResourceConfig object { file_id, type, mount_path }`
503 - `BetaManagedAgentsFileResourceConfig object`
551504
552505 A file mounted into each session's container.
553506
from line 510
557510
558511 - `type: "file"`
559512
560 - `"file"`
561
562513 - `mount_path: optional string or null`
563514
564515 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
565516
566 - `BetaManagedAgentsMemoryStoreResourceConfig object { memory_store_id, type, access, instructions }`
517 - `BetaManagedAgentsMemoryStoreResourceConfig object`
567518
568519 A memory store attached to each session created from this deployment.
569520
from line 524
573524
574525 - `type: "memory_store"`
575526
576 - `"memory_store"`
577
578527 - `access: optional "read_write" or "read_only" or null`
579528
580529 Access mode for an attached memory store.
from line 544
595544
596545 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).
597546
547 minLength: 1, maxLength: 256
548
598549 - `timezone: string`
599550
600551 IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").
601552
553 minLength: 1
554
602555 - `type: "cron"`
603556
604 - `"cron"`
605
606557 - `last_run_at: optional string or null`
607558
608559 A timestamp in RFC 3339 format
609560
561 format: date-time
562
610563 - `upcoming_runs_at: optional array of string`
611564
612565 Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.
from line 574
621574
622575 - `type: "deployment"`
623576
624 - `"deployment"`
625
626577 - `updated_at: string`
627578
628579 A timestamp in RFC 3339 format
629580
581 format: date-time
582
630583 - `vault_ids: array of string`
631584
632585 Vault IDs supplying stored credentials for sessions created from this deployment.
from line 600
647600
648601 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.
649602
650 - `"USD"`
651
652603 - `type: "limit"`
653604
654 - `"limit"`
605## Example
655606
656### Example
657
658```http
607```bash
659608curl https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/pause \
660609 -X POST \
661610 -H 'anthropic-version: 2023-06-01' \
from line 612
663612 -H "X-Api-Key: $ANTHROPIC_API_KEY"
664613```
665614
666#### Response
615### Response (200)
667616
668617```json
669618{