The whole hunk
from line 1, old and new numbered
/
lines
from line 1
1---
2title: Send Events
3url: https://platform.claude.com/docs/en/api/beta/sessions/events/send
4---
5
16# Send Events
27
38**POST** `/v1/sessions/{session_id}/events`
from line 21
1621
1722 - `string`
1823
19 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
24 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
2025
2126 - `"message-batches-2024-09-24"`
2227
from line 69
6469
6570 - `"user-profiles-2026-08-18"`
6671
72 - `"user-profiles-2026-09-04"`
73
6774 - `"advisor-tool-2026-03-01"`
6875
6976 - `"managed-agents-2026-04-01"`
from line 113
106113
107114 - `"mid-conversation-system-clear-at-2026-08-21"`
108115
116- `"anthropic-workspace-id": optional string`
117
109118## Body parameters
110119
111120- `events: array of BetaManagedAgentsEventParams`
from line 125
116125
117126 Parameters for sending a user message to the session.
118127
128 - `type: "user.message"`
129
119130 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
120131
121132 Array of content blocks for the user message.
from line 135
124135
125136 Regular text content.
126137
138 - `type: "text"`
139
127140 - `text: string`
128141
129142 The text content.
from line 143
130143
131144 minLength: 1
132145
133 - `type: "text"`
134
135146 - `BetaManagedAgentsImageBlock object`
136147
137148 Image content specified directly as base64 data or as a reference via a URL.
138149
150 - `type: "image"`
151
139152 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
140153
141154 Union type for image source variants.
from line 157
144157
145158 Base64-encoded image data.
146159
160 - `type: "base64"`
161
147162 - `data: string`
148163
149164 Base64-encoded image data.
from line 171
156171
157172 minLength: 1
158173
159 - `type: "base64"`
160
161174 - `BetaManagedAgentsURLImageSource object`
162175
163176 Image referenced by URL.
from line 187
174187
175188 Image referenced by file ID.
176189
190 - `type: "file"`
191
177192 - `file_id: string`
178193
179194 ID of a previously uploaded file.
from line 195
180195
181196 minLength: 1
182197
183 - `type: "file"`
184
185 - `type: "image"`
186
187198 - `BetaManagedAgentsDocumentBlock object`
188199
189200 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
190201
202 - `type: "document"`
203
191204 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
192205
193206 Union type for document source variants.
from line 209
196209
197210 Base64-encoded document data.
198211
212 - `type: "base64"`
213
199214 - `data: string`
200215
201216 Base64-encoded document data.
from line 223
208223
209224 minLength: 1
210225
211 - `type: "base64"`
212
213226 - `BetaManagedAgentsPlainTextDocumentSource object`
214227
215228 Plain text document content.
216229
230 - `type: "text"`
231
217232 - `data: string`
218233
219234 The plain text content.
from line 239
224239
225240 MIME type of the text content. Must be "text/plain".
226241
227 - `type: "text"`
228
229242 - `BetaManagedAgentsURLDocumentSource object`
230243
231244 Document referenced by URL.
from line 255
242255
243256 Document referenced by file ID.
244257
258 - `type: "file"`
259
245260 - `file_id: string`
246261
247262 ID of a previously uploaded file.
from line 263
248263
249264 minLength: 1
250265
251 - `type: "file"`
252
253 - `type: "document"`
254
255266 - `context: optional string or null`
256267
257268 Additional context about the document for the model.
from line 277
266277
267278 - `type: "redacted"`
268279
269 - `type: "user.message"`
270
271280 - `BetaManagedAgentsUserInterruptEventParams object`
272281
273282 Parameters for sending an interrupt to pause the agent.
from line 291
282291
283292 Parameters for confirming or denying a tool execution request.
284293
294 - `type: "user.tool_confirmation"`
295
285296 - `result: "allow" or "deny"`
286297
287298 UserToolConfirmationResult enum
from line 307
296307
297308 minLength: 1, maxLength: 128
298309
299 - `type: "user.tool_confirmation"`
300
301310 - `deny_message: optional string or null`
302311
303312 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
from line 317
308317
309318 Parameters for providing the result of a custom tool execution.
310319
320 - `type: "user.custom_tool_result"`
321
311322 - `custom_tool_use_id: string`
312323
313324 The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
from line 325
314325
315326 minLength: 1, maxLength: 128
316327
317 - `type: "user.custom_tool_result"`
318
319328 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
320329
321330 The result content returned by the tool.
from line 345
336345
337346 A block containing a web search result.
338347
348 - `type: "search_result"`
349
339350 - `citations: BetaManagedAgentsSearchResultCitations`
340351
341352 Citation settings for a search result.
from line 359
348359
349360 Array of text content blocks from the search result.
350361
362 - `type: "text"`
363
351364 - `text: string`
352365
353366 The text content.
from line 367
354367
355368 minLength: 1
356369
357 - `type: "text"`
358
359370 - `source: string`
360371
361372 The URL source of the search result.
from line 379
368379
369380 minLength: 1
370381
371 - `type: "search_result"`
372
373382 - `is_error: optional boolean or null`
374383
375384 Whether the tool execution resulted in an error.
from line 387
378387
379388 Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.
380389
390 - `type: "user.define_outcome"`
391
381392 - `description: string`
382393
383394 What the agent should produce. This is the task specification.
from line 401
390401
391402 Rubric referenced by a file uploaded via the Files API.
392403
404 - `type: "file"`
405
393406 - `file_id: string`
394407
395408 ID of the rubric file.
396409
397 - `type: "file"`
398
399410 - `BetaManagedAgentsTextRubricParams object`
400411
401412 Rubric content provided inline as text.
402413
414 - `type: "text"`
415
403416 - `content: string`
404417
405418 Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.
from line 419
406419
407420 maxLength: 262144
408421
409 - `type: "text"`
410
411 - `type: "user.define_outcome"`
412
413422 - `max_iterations: optional number or null`
414423
415424 Eval→revision cycles before giving up. Default 3, max 20.
from line 429
420429
421430 Parameters for providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.
422431
432 - `type: "user.tool_result"`
433
423434 - `tool_use_id: string`
424435
425436 The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
from line 437
426437
427438 minLength: 1, maxLength: 128
428439
429 - `type: "user.tool_result"`
430
431440 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
432441
433442 The result content returned by the tool.
from line 465
456465
457466 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.
458467
468 - `type: "system.message"`
469
459470 - `content: array of BetaManagedAgentsSystemContentBlock`
460471
461472 System content blocks to append. Text-only.
462473
474 - `type: "text"`
475
463476 - `text: string`
464477
465478 The text content.
from line 479
466479
467480 minLength: 1
468481
469 - `type: "text"`
470
471 - `type: "system.message"`
472
473482## Returns
474483
475484- `BetaManagedAgentsSendSessionEvents object`
from line 493
484493
485494 A user message event in the session conversation.
486495
496 - `type: "user.message"`
497
487498 - `id: string`
488499
489500 Unique identifier for this event.
from line 507
496507
497508 Regular text content.
498509
510 - `type: "text"`
511
499512 - `text: string`
500513
501514 The text content.
from line 515
502515
503516 minLength: 1
504517
505 - `type: "text"`
506
507518 - `BetaManagedAgentsImageBlock object`
508519
509520 Image content specified directly as base64 data or as a reference via a URL.
510521
522 - `type: "image"`
523
511524 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
512525
513526 Union type for image source variants.
from line 529
516529
517530 Base64-encoded image data.
518531
532 - `type: "base64"`
533
519534 - `data: string`
520535
521536 Base64-encoded image data.
from line 543
528543
529544 minLength: 1
530545
531 - `type: "base64"`
532
533546 - `BetaManagedAgentsURLImageSource object`
534547
535548 Image referenced by URL.
from line 559
546559
547560 Image referenced by file ID.
548561
562 - `type: "file"`
563
549564 - `file_id: string`
550565
551566 ID of a previously uploaded file.
from line 567
552567
553568 minLength: 1
554569
555 - `type: "file"`
556
557 - `type: "image"`
558
559570 - `BetaManagedAgentsDocumentBlock object`
560571
561572 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
562573
574 - `type: "document"`
575
563576 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
564577
565578 Union type for document source variants.
from line 581
568581
569582 Base64-encoded document data.
570583
584 - `type: "base64"`
585
571586 - `data: string`
572587
573588 Base64-encoded document data.
from line 595
580595
581596 minLength: 1
582597
583 - `type: "base64"`
584
585598 - `BetaManagedAgentsPlainTextDocumentSource object`
586599
587600 Plain text document content.
588601
602 - `type: "text"`
603
589604 - `data: string`
590605
591606 The plain text content.
from line 611
596611
597612 MIME type of the text content. Must be "text/plain".
598613
599 - `type: "text"`
600
601614 - `BetaManagedAgentsURLDocumentSource object`
602615
603616 Document referenced by URL.
from line 627
614627
615628 Document referenced by file ID.
616629
630 - `type: "file"`
631
617632 - `file_id: string`
618633
619634 ID of a previously uploaded file.
from line 635
620635
621636 minLength: 1
622637
623 - `type: "file"`
624
625 - `type: "document"`
626
627638 - `context: optional string or null`
628639
629640 Additional context about the document for the model.
from line 649
638649
639650 - `type: "redacted"`
640651
641 - `type: "user.message"`
642
643652 - `processed_at: optional string or null`
644653
645654 A timestamp in RFC 3339 format
from line 659
650659
651660 An interrupt event that pauses agent execution and returns control to the user.
652661
662 - `type: "user.interrupt"`
663
653664 - `id: string`
654665
655666 Unique identifier for this event.
656667
657 - `type: "user.interrupt"`
658
659668 - `processed_at: optional string or null`
660669
661670 A timestamp in RFC 3339 format
from line 679
670679
671680 A tool confirmation event that approves or denies a pending tool execution.
672681
682 - `type: "user.tool_confirmation"`
683
673684 - `id: string`
674685
675686 Unique identifier for this event.
from line 697
686697
687698 The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
688699
689 - `type: "user.tool_confirmation"`
690
691700 - `deny_message: optional string or null`
692701
693702 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
from line 717
708717
709718 Event sent by the client providing the result of a custom tool execution.
710719
720 - `type: "user.custom_tool_result"`
721
711722 - `id: string`
712723
713724 Unique identifier for this event.
from line 727
716727
717728 The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
718729
719 - `type: "user.custom_tool_result"`
720
721730 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
722731
723732 The result content returned by the tool.
from line 747
738747
739748 A block containing a web search result.
740749
750 - `type: "search_result"`
751
741752 - `citations: BetaManagedAgentsSearchResultCitations`
742753
743754 Citation settings for a search result.
from line 761
750761
751762 Array of text content blocks from the search result.
752763
764 - `type: "text"`
765
753766 - `text: string`
754767
755768 The text content.
from line 769
756769
757770 minLength: 1
758771
759 - `type: "text"`
760
761772 - `source: string`
762773
763774 The URL source of the search result.
from line 781
770781
771782 minLength: 1
772783
773 - `type: "search_result"`
774
775784 - `is_error: optional boolean or null`
776785
777786 Whether the tool execution resulted in an error.
from line 799
790799
791800 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
792801
802 - `type: "user.define_outcome"`
803
793804 - `id: string`
794805
795806 Unique identifier for this event.
from line 833
822833
823834 Rubric referenced by a file uploaded via the Files API.
824835
836 - `type: "file"`
837
825838 - `file_id: string`
826839
827840 ID of the rubric file.
828841
829 - `type: "file"`
830
831842 - `BetaManagedAgentsTextRubric object`
832843
833844 Rubric content provided inline as text.
834845
846 - `type: "text"`
847
835848 - `content: string`
836849
837850 Rubric content. Plain text or markdown — the grader treats it as freeform text.
838851
839 - `type: "text"`
840
841 - `type: "user.define_outcome"`
842
843852 - `BetaManagedAgentsUserToolResultEvent object`
844853
845854 Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.
846855
856 - `type: "user.tool_result"`
857
847858 - `id: string`
848859
849860 Unique identifier for this event.
from line 863
852863
853864 The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
854865
855 - `type: "user.tool_result"`
856
857866 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
858867
859868 The result content returned by the tool.
from line 901
892901
893902 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
894903
904 - `type: "system.message"`
905
895906 - `id: string`
896907
897908 Unique identifier for this event.
from line 911
900911
901912 System content blocks. Text-only.
902913
914 - `type: "text"`
915
903916 - `text: string`
904917
905918 The text content.
906919
907920 minLength: 1
908
909 - `type: "text"`
910
911 - `type: "system.message"`
912921
913922 - `processed_at: optional string or null`
914923