Update Session changedapi/beta/sessions/update
Nearest release: v2.1.245, published an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+178added
Lines−245removed
From line
1
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits23to this page, all time
# Update Session ## Path parameters ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Update Session ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
The whole hunk
from line 1, old and new numbered
/
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: Update Session
3url: https://platform.claude.com/docs/en/api/beta/sessions/update
4---
5
6## Update Session
7
8**post** `/v1/sessions/{session_id}`
1# Update Session
2
3**POST** `/v1/sessions/{session_id}`
94
105Update Session
116
12### Path Parameters
7## Path parameters
138
149- `session_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- `agent: optional BetaManagedAgentsSessionAgentUpdate`
9792
from line 100
105100
106101 Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.
107102
103 minLength: 1, maxLength: 255
104
108105 - `type: "url"`
109106
110 - `"url"`
111
112107 - `url: string`
113108
114109 Endpoint URL for the MCP server.
115110
111 maxLength: 2048
112
116113 - `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams`
117114
118115 Replacement tool list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve.
119116
120 - `BetaManagedAgentsAgentToolset20260401Params object { type, configs, default_config }`
117 - `BetaManagedAgentsAgentToolset20260401Params object`
121118
122119 Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.
123120
124121 - `type: "agent_toolset_20260401"`
125122
126 - `"agent_toolset_20260401"`
127
128123 - `configs: optional array of BetaManagedAgentsAgentToolConfigParams`
129124
130125 Per-tool configuration overrides.
131126
132 - `BetaManagedAgentsBashToolConfigParams object { name, enabled, permission_policy, type }`
127 - `BetaManagedAgentsBashToolConfigParams object`
133128
134129 Configuration override for the bash tool.
135130
from line 132
137132
138133 Must be "bash".
139134
140 - `"bash"`
141
142135 - `enabled: optional boolean or null`
143136
144137 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 140
147140
148141 Permission policy for tool execution.
149142
150 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
143 - `BetaManagedAgentsAlwaysAllowPolicy object`
151144
152145 Tool calls are automatically approved without user confirmation.
153146
154147 - `type: "always_allow"`
155148
156 - `"always_allow"`
157
158 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
149 - `BetaManagedAgentsAlwaysAskPolicy object`
159150
160151 Tool calls require user confirmation before execution.
161152
162153 - `type: "always_ask"`
163154
164 - `"always_ask"`
165
166155 - `type: optional "bash"`
167156
168 - `"bash"`
169
170 - `BetaManagedAgentsEditToolConfigParams object { name, enabled, permission_policy, type }`
157 - `BetaManagedAgentsEditToolConfigParams object`
171158
172159 Configuration override for the edit tool.
173160
from line 162
175162
176163 Must be "edit".
177164
178 - `"edit"`
179
180165 - `enabled: optional boolean or null`
181166
182167 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 170
185170
186171 Permission policy for tool execution.
187172
188 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
173 - `BetaManagedAgentsAlwaysAllowPolicy object`
189174
190175 Tool calls are automatically approved without user confirmation.
191176
192 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
177 - `BetaManagedAgentsAlwaysAskPolicy object`
193178
194179 Tool calls require user confirmation before execution.
195180
196181 - `type: optional "edit"`
197182
198 - `"edit"`
199
200 - `BetaManagedAgentsReadToolConfigParams object { name, enabled, permission_policy, type }`
183 - `BetaManagedAgentsReadToolConfigParams object`
201184
202185 Configuration override for the read tool.
203186
from line 188
205188
206189 Must be "read".
207190
208 - `"read"`
209
210191 - `enabled: optional boolean or null`
211192
212193 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 196
215196
216197 Permission policy for tool execution.
217198
218 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
199 - `BetaManagedAgentsAlwaysAllowPolicy object`
219200
220201 Tool calls are automatically approved without user confirmation.
221202
222 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
203 - `BetaManagedAgentsAlwaysAskPolicy object`
223204
224205 Tool calls require user confirmation before execution.
225206
226207 - `type: optional "read"`
227208
228 - `"read"`
229
230 - `BetaManagedAgentsWriteToolConfigParams object { name, enabled, permission_policy, type }`
209 - `BetaManagedAgentsWriteToolConfigParams object`
231210
232211 Configuration override for the write tool.
233212
from line 214
235214
236215 Must be "write".
237216
238 - `"write"`
239
240217 - `enabled: optional boolean or null`
241218
242219 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 222
245222
246223 Permission policy for tool execution.
247224
248 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
225 - `BetaManagedAgentsAlwaysAllowPolicy object`
249226
250227 Tool calls are automatically approved without user confirmation.
251228
252 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
229 - `BetaManagedAgentsAlwaysAskPolicy object`
253230
254231 Tool calls require user confirmation before execution.
255232
256233 - `type: optional "write"`
257234
258 - `"write"`
259
260 - `BetaManagedAgentsGlobToolConfigParams object { name, enabled, permission_policy, type }`
235 - `BetaManagedAgentsGlobToolConfigParams object`
261236
262237 Configuration override for the glob tool.
263238
from line 240
265240
266241 Must be "glob".
267242
268 - `"glob"`
269
270243 - `enabled: optional boolean or null`
271244
272245 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 248
275248
276249 Permission policy for tool execution.
277250
278 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
251 - `BetaManagedAgentsAlwaysAllowPolicy object`
279252
280253 Tool calls are automatically approved without user confirmation.
281254
282 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
255 - `BetaManagedAgentsAlwaysAskPolicy object`
283256
284257 Tool calls require user confirmation before execution.
285258
286259 - `type: optional "glob"`
287260
288 - `"glob"`
289
290 - `BetaManagedAgentsGrepToolConfigParams object { name, enabled, permission_policy, type }`
261 - `BetaManagedAgentsGrepToolConfigParams object`
291262
292263 Configuration override for the grep tool.
293264
from line 266
295266
296267 Must be "grep".
297268
298 - `"grep"`
299
300269 - `enabled: optional boolean or null`
301270
302271 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 274
305274
306275 Permission policy for tool execution.
307276
308 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
277 - `BetaManagedAgentsAlwaysAllowPolicy object`
309278
310279 Tool calls are automatically approved without user confirmation.
311280
312 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
281 - `BetaManagedAgentsAlwaysAskPolicy object`
313282
314283 Tool calls require user confirmation before execution.
315284
316285 - `type: optional "grep"`
317286
318 - `"grep"`
319
320 - `BetaManagedAgentsWebFetchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }`
287 - `BetaManagedAgentsWebFetchToolConfigParams object`
321288
322289 Configuration override for the web_fetch tool.
323290
from line 292
325292
326293 Must be "web_fetch".
327294
328 - `"web_fetch"`
329
330295 - `allowed_domains: optional array of string`
331296
332297 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 308
343308
344309 Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs.
345310
311 format: int32
312
346313 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
347314
348315 Permission policy for tool execution.
349316
350 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
317 - `BetaManagedAgentsAlwaysAllowPolicy object`
351318
352319 Tool calls are automatically approved without user confirmation.
353320
354 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
321 - `BetaManagedAgentsAlwaysAskPolicy object`
355322
356323 Tool calls require user confirmation before execution.
357324
358325 - `type: optional "web_fetch"`
359326
360 - `"web_fetch"`
361
362 - `BetaManagedAgentsWebSearchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }`
327 - `BetaManagedAgentsWebSearchToolConfigParams object`
363328
364329 Configuration override for the web_search tool.
365330
from line 332
367332
368333 Must be "web_search".
369334
370 - `"web_search"`
371
372335 - `allowed_domains: optional array of string`
373336
374337 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 348
385348
386349 Permission policy for tool execution.
387350
388 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
351 - `BetaManagedAgentsAlwaysAllowPolicy object`
389352
390353 Tool calls are automatically approved without user confirmation.
391354
392 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
355 - `BetaManagedAgentsAlwaysAskPolicy object`
393356
394357 Tool calls require user confirmation before execution.
395358
396359 - `type: optional "web_search"`
397360
398 - `"web_search"`
399
400361 - `user_location: optional BetaManagedAgentsUserLocation or null`
401362
402363 Approximate user location for search result localization.
from line 366
405366
406367 Location precision. Only "approximate" is supported.
407368
408 - `"approximate"`
409
410369 - `city: optional string or null`
411370
412371 City name.
413372
373 minLength: 1, maxLength: 255
374
414375 - `country: optional string or null`
415376
416377 Two-letter ISO 3166-1 country code, uppercase.
from line 380
419380
420381 Region or state name.
421382
383 minLength: 1, maxLength: 255
384
422385 - `timezone: optional string or null`
423386
424387 IANA timezone identifier, e.g. "America/Los_Angeles".
425388
389 minLength: 1, maxLength: 255
390
426391 - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or null`
427392
428393 Default configuration for all tools in a toolset.
from line 400
435400
436401 Permission policy for tool execution.
437402
438 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
403 - `BetaManagedAgentsAlwaysAllowPolicy object`
439404
440405 Tool calls are automatically approved without user confirmation.
441406
442 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
407 - `BetaManagedAgentsAlwaysAskPolicy object`
443408
444409 Tool calls require user confirmation before execution.
445410
446 - `BetaManagedAgentsMCPToolsetParams object { mcp_server_name, type, configs, default_config }`
411 - `BetaManagedAgentsMCPToolsetParams object`
447412
448413 Configuration for tools from an MCP server defined in `mcp_servers`.
449414
from line 416
451416
452417 Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.
453418
419 minLength: 1, maxLength: 255
420
454421 - `type: "mcp_toolset"`
455422
456 - `"mcp_toolset"`
457
458423 - `configs: optional array of BetaManagedAgentsMCPToolConfigParams`
459424
460425 Per-tool configuration overrides.
from line 428
463428
464429 Name of the MCP tool to configure. 1-128 characters.
465430
431 minLength: 1, maxLength: 128
432
466433 - `enabled: optional boolean or null`
467434
468435 Whether this tool is enabled. Overrides the `default_config` setting.
from line 438
471438
472439 Permission policy for tool execution.
473440
474 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
441 - `BetaManagedAgentsAlwaysAllowPolicy object`
475442
476443 Tool calls are automatically approved without user confirmation.
477444
478 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
445 - `BetaManagedAgentsAlwaysAskPolicy object`
479446
480447 Tool calls require user confirmation before execution.
481448
from line 458
491458
492459 Permission policy for tool execution.
493460
494 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
461 - `BetaManagedAgentsAlwaysAllowPolicy object`
495462
496463 Tool calls are automatically approved without user confirmation.
497464
498 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
465 - `BetaManagedAgentsAlwaysAskPolicy object`
499466
500467 Tool calls require user confirmation before execution.
501468
502 - `BetaManagedAgentsCustomToolParams object { description, input_schema, name, type }`
469 - `BetaManagedAgentsCustomToolParams object`
503470
504471 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.
505472
from line 474
507474
508475 Description of what the tool does, shown to the agent to help it decide when to use the tool.
509476
477 minLength: 1
478
510479 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
511480
512481 JSON Schema for custom tool input parameters.
513482
514483 - `type: "object"`
515484
516 - `"object"`
517
518485 - `properties: optional map[unknown] or null`
519486
520487 - `required: optional array of string or null`
from line 490
523490
524491 Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.
525492
493 minLength: 1, maxLength: 128
494
526495 - `type: "custom"`
527496
528 - `"custom"`
529
530497- `budget: optional BetaManagedAgentsBudgetLimit or null`
531498
532499 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 510
543510
544511 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.
545512
546 - `"USD"`
547
548513 - `type: "limit"`
549514
550 - `"limit"`
551
552515- `metadata: optional map[string] or null`
553516
554517 Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve.
from line 520
557520
558521 Human-readable session title.
559522
523 minLength: 1, maxLength: 500
524
560525- `vault_ids: optional array of string`
561526
562527 Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use.
563528
564### Returns
565
566- `BetaManagedAgentsSession object { id, agent, archived_at, 14 more }`
529## Returns
530
531- `BetaManagedAgentsSession object`
567532
568533 A Managed Agents `session`.
569534
from line 548
583548
584549 - `type: "url"`
585550
586 - `"url"`
587
588551 - `url: string`
589552
590553 - `model: BetaManagedAgentsModelConfig`
from line 624
661624
662625 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
663626
664 - `BetaManagedAgentsEffortLow object { type }`
627 - `BetaManagedAgentsEffortLow object`
665628
666629 Low effort. Favors latency over reasoning depth.
667630
668631 - `type: "low"`
669632
670 - `"low"`
671
672 - `BetaManagedAgentsEffortMedium object { type }`
633 - `BetaManagedAgentsEffortMedium object`
673634
674635 Medium effort. Balances latency and reasoning depth.
675636
676637 - `type: "medium"`
677638
678 - `"medium"`
679
680 - `BetaManagedAgentsEffortHigh object { type }`
639 - `BetaManagedAgentsEffortHigh object`
681640
682641 High effort. Favors reasoning depth.
683642
684643 - `type: "high"`
685644
686 - `"high"`
687
688 - `BetaManagedAgentsEffortXhigh object { type }`
645 - `BetaManagedAgentsEffortXhigh object`
689646
690647 Extra-high effort. Not all models accept this level.
691648
692649 - `type: "xhigh"`
693650
694 - `"xhigh"`
695
696 - `BetaManagedAgentsEffortMax object { type }`
651 - `BetaManagedAgentsEffortMax object`
697652
698653 Maximum effort. Favors reasoning depth over latency.
699654
700655 - `type: "max"`
701656
702 - `"max"`
703
704657 - `inference_geo: optional string`
705658
706659 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 674
721674
722675 Full `agent` definitions the coordinator may spawn as session threads.
723676
724 - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }`
677 - `BetaManagedAgentsSessionThreadAgent object`
725678
726679 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`.
727680
from line 698
745698
746699 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
747700
748 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
701 - `BetaManagedAgentsAnthropicSkill object`
749702
750703 A resolved Anthropic-managed skill.
751704
from line 706
753706
754707 - `type: "anthropic"`
755708
756 - `"anthropic"`
757
758709 - `version: string`
759710
760 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
711 - `BetaManagedAgentsCustomSkill object`
761712
762713 A resolved user-created custom skill.
763714
from line 716
765716
766717 - `type: "custom"`
767718
768 - `"custom"`
769
770719 - `version: string`
771720
772721 - `system: string or null`
773722
774723 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
775724
776 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
725 - `BetaManagedAgentsAgentToolset20260401 object`
777726
778727 - `configs: array of BetaManagedAgentsAgentToolConfig`
779728
780 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
729 - `BetaManagedAgentsBashToolConfig object`
781730
782731 Configuration for the bash tool.
783732
from line 734
785734
786735 - `name: "bash"`
787736
788 - `"bash"`
789
790737 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
791738
792739 Permission policy for tool execution.
793740
794 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
741 - `BetaManagedAgentsAlwaysAllowPolicy object`
795742
796743 Tool calls are automatically approved without user confirmation.
797744
798745 - `type: "always_allow"`
799746
800 - `"always_allow"`
801
802 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
747 - `BetaManagedAgentsAlwaysAskPolicy object`
803748
804749 Tool calls require user confirmation before execution.
805750
806751 - `type: "always_ask"`
807752
808 - `"always_ask"`
809
810753 - `type: "bash"`
811754
812 - `"bash"`
813
814 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
755 - `BetaManagedAgentsEditToolConfig object`
815756
816757 Configuration for the edit tool.
817758
from line 760
819760
820761 - `name: "edit"`
821762
822 - `"edit"`
823
824763 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
825764
826765 Permission policy for tool execution.
827766
828 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
767 - `BetaManagedAgentsAlwaysAllowPolicy object`
829768
830769 Tool calls are automatically approved without user confirmation.
831770
832 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
771 - `BetaManagedAgentsAlwaysAskPolicy object`
833772
834773 Tool calls require user confirmation before execution.
835774
836775 - `type: "edit"`
837776
838 - `"edit"`
839
840 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
777 - `BetaManagedAgentsReadToolConfig object`
841778
842779 Configuration for the read tool.
843780
from line 782
845782
846783 - `name: "read"`
847784
848 - `"read"`
849
850785 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
851786
852787 Permission policy for tool execution.
853788
854 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
789 - `BetaManagedAgentsAlwaysAllowPolicy object`
855790
856791 Tool calls are automatically approved without user confirmation.
857792
858 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
793 - `BetaManagedAgentsAlwaysAskPolicy object`
859794
860795 Tool calls require user confirmation before execution.
861796
862797 - `type: "read"`
863798
864 - `"read"`
865
866 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
799 - `BetaManagedAgentsWriteToolConfig object`
867800
868801 Configuration for the write tool.
869802
from line 804
871804
872805 - `name: "write"`
873806
874 - `"write"`
875
876807 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
877808
878809 Permission policy for tool execution.
879810
880 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
811 - `BetaManagedAgentsAlwaysAllowPolicy object`
881812
882813 Tool calls are automatically approved without user confirmation.
883814
884 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
815 - `BetaManagedAgentsAlwaysAskPolicy object`
885816
886817 Tool calls require user confirmation before execution.
887818
888819 - `type: "write"`
889820
890 - `"write"`
891
892 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
821 - `BetaManagedAgentsGlobToolConfig object`
893822
894823 Configuration for the glob tool.
895824
from line 826
897826
898827 - `name: "glob"`
899828
900 - `"glob"`
901
902829 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
903830
904831 Permission policy for tool execution.
905832
906 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
833 - `BetaManagedAgentsAlwaysAllowPolicy object`
907834
908835 Tool calls are automatically approved without user confirmation.
909836
910 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
837 - `BetaManagedAgentsAlwaysAskPolicy object`
911838
912839 Tool calls require user confirmation before execution.
913840
914841 - `type: "glob"`
915842
916 - `"glob"`
917
918 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
843 - `BetaManagedAgentsGrepToolConfig object`
919844
920845 Configuration for the grep tool.
921846
from line 848
923848
924849 - `name: "grep"`
925850
926 - `"grep"`
927
928851 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
929852
930853 Permission policy for tool execution.
931854
932 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
855 - `BetaManagedAgentsAlwaysAllowPolicy object`
933856
934857 Tool calls are automatically approved without user confirmation.
935858
936 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
859 - `BetaManagedAgentsAlwaysAskPolicy object`
937860
938861 Tool calls require user confirmation before execution.
939862
940863 - `type: "grep"`
941864
942 - `"grep"`
943
944 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
865 - `BetaManagedAgentsWebFetchToolConfig object`
945866
946867 Configuration for the web_fetch tool.
947868
from line 870
949870
950871 - `name: "web_fetch"`
951872
952 - `"web_fetch"`
953
954873 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
955874
956875 Permission policy for tool execution.
957876
958 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
877 - `BetaManagedAgentsAlwaysAllowPolicy object`
959878
960879 Tool calls are automatically approved without user confirmation.
961880
962 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
881 - `BetaManagedAgentsAlwaysAskPolicy object`
963882
964883 Tool calls require user confirmation before execution.
965884
966885 - `type: "web_fetch"`
967886
968 - `"web_fetch"`
969
970887 - `allowed_domains: optional array of string`
971888
972889 - `blocked_domains: optional array of string`
973890
974891 - `max_content_tokens: optional number or null`
975892
976 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
893 format: int32
894
895 - `BetaManagedAgentsWebSearchToolConfig object`
977896
978897 Configuration for the web_search tool.
979898
from line 900
981900
982901 - `name: "web_search"`
983902
984 - `"web_search"`
985
986903 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
987904
988905 Permission policy for tool execution.
989906
990 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
907 - `BetaManagedAgentsAlwaysAllowPolicy object`
991908
992909 Tool calls are automatically approved without user confirmation.
993910
994 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
911 - `BetaManagedAgentsAlwaysAskPolicy object`
995912
996913 Tool calls require user confirmation before execution.
997914
998915 - `type: "web_search"`
999916
1000 - `"web_search"`
1001
1002917 - `allowed_domains: optional array of string`
1003918
1004919 - `blocked_domains: optional array of string`
from line 926
1011926
1012927 Location precision. Only "approximate" is supported.
1013928
1014 - `"approximate"`
1015
1016929 - `city: optional string or null`
1017930
1018931 City name.
1019932
933 minLength: 1, maxLength: 255
934
1020935 - `country: optional string or null`
1021936
1022937 Two-letter ISO 3166-1 country code, uppercase.
from line 940
1025940
1026941 Region or state name.
1027942
943 minLength: 1, maxLength: 255
944
1028945 - `timezone: optional string or null`
1029946
1030947 IANA timezone identifier, e.g. "America/Los_Angeles".
1031948
949 minLength: 1, maxLength: 255
950
1032951 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
1033952
1034953 Resolved default configuration for agent tools.
from line 958
1039958
1040959 Permission policy for tool execution.
1041960
1042 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
961 - `BetaManagedAgentsAlwaysAllowPolicy object`
1043962
1044963 Tool calls are automatically approved without user confirmation.
1045964
1046 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
965 - `BetaManagedAgentsAlwaysAskPolicy object`
1047966
1048967 Tool calls require user confirmation before execution.
1049968
1050969 - `type: "agent_toolset_20260401"`
1051970
1052 - `"agent_toolset_20260401"`
1053
1054 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
971 - `BetaManagedAgentsMCPToolset object`
1055972
1056973 - `configs: array of BetaManagedAgentsMCPToolConfig`
1057974
from line 980
1063980
1064981 Permission policy for tool execution.
1065982
1066 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
983 - `BetaManagedAgentsAlwaysAllowPolicy object`
1067984
1068985 Tool calls are automatically approved without user confirmation.
1069986
1070 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
987 - `BetaManagedAgentsAlwaysAskPolicy object`
1071988
1072989 Tool calls require user confirmation before execution.
1073990
from line 998
1081998
1082999 Permission policy for tool execution.
10831000
1084 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1001 - `BetaManagedAgentsAlwaysAllowPolicy object`
10851002
10861003 Tool calls are automatically approved without user confirmation.
10871004
1088 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1005 - `BetaManagedAgentsAlwaysAskPolicy object`
10891006
10901007 Tool calls require user confirmation before execution.
10911008
from line 1010
10931010
10941011 - `type: "mcp_toolset"`
10951012
1096 - `"mcp_toolset"`
1097
1098 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
1013 - `BetaManagedAgentsCustomTool object`
10991014
11001015 A custom tool as returned in API responses.
11011016
from line 1022
11071022
11081023 - `type: "object"`
11091024
1110 - `"object"`
1111
11121025 - `properties: optional map[unknown] or null`
11131026
11141027 - `required: optional array of string or null`
from line 1030
11171030
11181031 - `type: "custom"`
11191032
1120 - `"custom"`
1121
11221033 - `type: "agent"`
11231034
1124 - `"agent"`
1125
11261035 - `version: number`
11271036
1128 - `BetaManagedAgentsAdvisor object { model, type }`
1037 format: int32
1038
1039 - `BetaManagedAgentsAdvisor object`
11291040
11301041 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
11311042
from line 1046
11351046
11361047 - `type: "advisor"`
11371048
1138 - `"advisor"`
1139
11401049 - `type: "coordinator"`
11411050
1142 - `"coordinator"`
1143
11441051 - `name: string`
11451052
11461053 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
11471054
1148 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
1055 - `BetaManagedAgentsAnthropicSkill object`
11491056
11501057 A resolved Anthropic-managed skill.
11511058
1152 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
1059 - `BetaManagedAgentsCustomSkill object`
11531060
11541061 A resolved user-created custom skill.
11551062
from line 1064
11571064
11581065 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
11591066
1160 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
1161
1162 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
1163
1164 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
1067 - `BetaManagedAgentsAgentToolset20260401 object`
1068
1069 - `BetaManagedAgentsMCPToolset object`
1070
1071 - `BetaManagedAgentsCustomTool object`
11651072
11661073 A custom tool as returned in API responses.
11671074
11681075 - `type: "agent"`
11691076
1170 - `"agent"`
1171
11721077 - `version: number`
11731078
1079 format: int32
1080
11741081 - `archived_at: string or null`
11751082
11761083 A timestamp in RFC 3339 format
11771084
1085 format: date-time
1086
11781087 - `budget: BetaManagedAgentsBudgetLimit or null`
11791088
11801089 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 1100
11911100
11921101 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.
11931102
1194 - `"USD"`
1195
11961103 - `type: "limit"`
11971104
1198 - `"limit"`
1199
12001105 - `created_at: string`
12011106
12021107 A timestamp in RFC 3339 format
12031108
1109 format: date-time
1110
12041111 - `environment_id: string`
12051112
12061113 - `metadata: map[string]`
from line 1120
12131120
12141121 A timestamp in RFC 3339 format
12151122
1123 format: date-time
1124
12161125 - `description: string`
12171126
12181127 What the agent should produce.
from line 1134
12251134
12261135 0-indexed revision cycle the outcome is currently on.
12271136
1137 format: int32
1138
12281139 - `outcome_id: string`
12291140
12301141 Server-generated outc_ ID for this outcome.
from line 1146
12351146
12361147 - `type: "outcome_evaluation"`
12371148
1238 - `"outcome_evaluation"`
1239
12401149 - `resources: array of BetaManagedAgentsSessionResource`
12411150
1242 - `BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }`
1151 - `BetaManagedAgentsGitHubRepositoryResource object`
12431152
12441153 - `id: string`
12451154
from line 1156
12471156
12481157 A timestamp in RFC 3339 format
12491158
1159 format: date-time
1160
12501161 - `mount_path: string`
12511162
12521163 - `type: "github_repository"`
12531164
1254 - `"github_repository"`
1255
12561165 - `updated_at: string`
12571166
12581167 A timestamp in RFC 3339 format
12591168
1169 format: date-time
1170
12601171 - `url: string`
12611172
12621173 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
12631174
1264 - `BetaManagedAgentsBranchCheckout object { name, type }`
1175 - `BetaManagedAgentsBranchCheckout object`
12651176
12661177 - `name: string`
12671178
12681179 Branch name to check out.
12691180
1181 minLength: 1, maxLength: 255
1182
12701183 - `type: "branch"`
12711184
1272 - `"branch"`
1273
1274 - `BetaManagedAgentsCommitCheckout object { sha, type }`
1185 - `BetaManagedAgentsCommitCheckout object`
12751186
12761187 - `sha: string`
12771188
12781189 Full commit SHA to check out.
12791190
1191 minLength: 7, maxLength: 64
1192
12801193 - `type: "commit"`
12811194
1282 - `"commit"`
1283
1284 - `BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }`
1195 - `BetaManagedAgentsFileResource object`
12851196
12861197 - `id: string`
12871198
from line 1200
12891200
12901201 A timestamp in RFC 3339 format
12911202
1203 format: date-time
1204
12921205 - `file_id: string`
12931206
12941207 - `mount_path: string`
12951208
12961209 - `type: "file"`
12971210
1298 - `"file"`
1299
13001211 - `updated_at: string`
13011212
13021213 A timestamp in RFC 3339 format
13031214
1304 - `BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }`
1215 format: date-time
1216
1217 - `BetaManagedAgentsMemoryStoreResource object`
13051218
13061219 A memory store attached to an agent session.
13071220
from line 1224
13111224
13121225 - `type: "memory_store"`
13131226
1314 - `"memory_store"`
1315
13161227 - `access: optional "read_write" or "read_only" or null`
13171228
13181229 Access mode for an attached memory store.
from line 1240
13291240
13301241 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
13311242
1243 maxLength: 4096
1244
13321245 - `mount_path: optional string or null`
13331246
13341247 Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.
from line 1258
13451258
13461259 Cumulative time in seconds the session spent in running status. Excludes idle time.
13471260
1261 format: double
1262
13481263 - `duration_seconds: optional number`
13491264
13501265 Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.
13511266
1267 format: double
1268
13521269 - `status: "rescheduling" or "running" or "idle" or "terminated"`
13531270
13541271 SessionStatus enum
from line 1282
13651282
13661283 - `type: "session"`
13671284
1368 - `"session"`
1369
13701285 - `updated_at: string`
13711286
13721287 A timestamp in RFC 3339 format
13731288
1289 format: date-time
1290
13741291 - `usage: BetaManagedAgentsSessionUsage`
13751292
13761293 Cumulative token usage for a session across all turns.
from line 1296
13791296
13801297 Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike `stats.active_seconds`, which sums each thread's own active time. This is the duration the session's runtime cost is priced on.
13811298
1299 format: double
1300
13821301 - `cache_creation: optional BetaManagedAgentsCacheCreationUsage`
13831302
13841303 Prompt-cache creation token usage broken down by cache lifetime.
from line 1306
13871306
13881307 Tokens used to create 1-hour ephemeral cache entries.
13891308
1309 format: int32
1310
13901311 - `ephemeral_5m_input_tokens: optional number`
13911312
13921313 Tokens used to create 5-minute ephemeral cache entries.
13931314
1315 format: int32
1316
13941317 - `cache_read_input_tokens: optional number`
13951318
13961319 Total tokens read from prompt cache.
13971320
1321 format: int32
1322
13981323 - `input_tokens: optional number`
13991324
14001325 Total input tokens consumed across all turns.
14011326
1327 format: int32
1328
14021329 - `list_cost: optional BetaMonetaryAmount or null`
14031330
14041331 A monetary amount in a specific currency.
from line 1334
14071334
14081335 Total output tokens generated across all turns.
14091336
1337 format: int32
1338
14101339 - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null`
14111340
14121341 Cumulative count of server-executed tool invocations, broken down by tool.
from line 1344
14151344
14161345 Number of server-executed web fetch requests.
14171346
1347 format: int32
1348
14181349 - `web_search_requests: optional number`
14191350
14201351 Number of server-executed web search requests.
14211352
1353 format: int32
1354
14221355 - `vault_ids: array of string`
14231356
14241357 Vault IDs attached to the session at creation. Empty when no vaults were supplied.
from line 1360
14271360
14281361 Deployment ID when the session was created from a deployment reference. Null otherwise.
14291362
1430### Example
1431
1432```http
1363## Example
1364
1365```bash
14331366curl https://api.anthropic.com/v1/sessions/$SESSION_ID \
14341367 -H 'Content-Type: application/json' \
14351368 -H 'anthropic-version: 2023-06-01' \
from line 1373
14401373 }'
14411374```
14421375
1443#### Response
1376### Response (200)
14441377
14451378```json
14461379{
14471380
No line in this hunk matches that.