Repository Public
1---2title: Send Events3url: https://platform.claude.com/docs/en/api/beta/sessions/events/send4---56# Send Events78**POST** `/v1/sessions/{session_id}/events`910Send Events1112## Path parameters1314- `session_id: string`1516## Headers1718- `"anthropic-beta": optional array of AnthropicBeta`1920 Optional header to specify the beta version(s) you want to use.2122 - `string`2324 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more`2526 - `"message-batches-2024-09-24"`2728 - `"prompt-caching-2024-07-31"`2930 - `"computer-use-2024-10-22"`3132 - `"computer-use-2025-01-24"`3334 - `"pdfs-2024-09-25"`3536 - `"token-counting-2024-11-01"`3738 - `"token-efficient-tools-2025-02-19"`3940 - `"output-128k-2025-02-19"`4142 - `"files-api-2025-04-14"`4344 - `"mcp-client-2025-04-04"`4546 - `"mcp-client-2025-11-20"`4748 - `"dev-full-thinking-2025-05-14"`4950 - `"interleaved-thinking-2025-05-14"`5152 - `"code-execution-2025-05-22"`5354 - `"extended-cache-ttl-2025-04-11"`5556 - `"context-1m-2025-08-07"`5758 - `"context-management-2025-06-27"`5960 - `"model-context-window-exceeded-2025-08-26"`6162 - `"skills-2025-10-02"`6364 - `"fast-mode-2026-02-01"`6566 - `"output-300k-2026-03-24"`6768 - `"user-profiles-2026-03-24"`6970 - `"user-profiles-2026-08-18"`7172 - `"user-profiles-2026-09-04"`7374 - `"advisor-tool-2026-03-01"`7576 - `"managed-agents-2026-04-01"`7778 - `"cache-diagnosis-2026-04-07"`7980 - `"dreaming-2026-04-21"`8182 - `"thinking-token-count-2026-05-13"`8384 - `"server-side-fallback-2026-06-01"`8586 - `"server-side-fallback-2026-07-01"`8788 - `"fallback-credit-2026-06-01"`8990 - `"fallback-credit-2026-07-01"`9192 - `"agent-memory-2026-07-22"`9394 - `"mid-conversation-tool-changes-2026-07-01"`9596 - `"compact-2026-01-12"`9798 - `"computer-use-2025-11-24"`99100 - `"mcp-tunnels-2026-06-22"`101102 - `"structured-outputs-2025-11-13"`103104 - `"task-budgets-2026-03-13"`105106 - `"thinking-display-updates-2026-08-18"`107108 - `"ce-user-management-2026-07-13"`109110 - `"mid-conversation-output-config-2026-07-01"`111112 - `"thinking-binding-controls-2026-08-01"`113114 - `"mid-conversation-system-clear-at-2026-08-21"`115116 - `"compact-2026-09-04"`117118- `"anthropic-workspace-id": optional string`119120## Body parameters121122- `events: array of BetaManagedAgentsEventParams`123124 Events to send to the `session`.125126 - `BetaManagedAgentsUserMessageEventParams object`127128 Parameters for sending a user message to the session.129130 - `type: "user.message"`131132 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`133134 Array of content blocks for the user message.135136 - `BetaManagedAgentsTextBlock object`137138 Regular text content.139140 - `type: "text"`141142 - `text: string`143144 The text content.145146 minLength: 1147148 - `BetaManagedAgentsImageBlock object`149150 Image content specified directly as base64 data or as a reference via a URL.151152 - `type: "image"`153154 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`155156 Union type for image source variants.157158 - `BetaManagedAgentsBase64ImageSource object`159160 Base64-encoded image data.161162 - `type: "base64"`163164 - `data: string`165166 Base64-encoded image data.167168 minLength: 1169170 - `media_type: string`171172 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").173174 minLength: 1175176 - `BetaManagedAgentsURLImageSource object`177178 Image referenced by URL.179180 - `type: "url"`181182 - `url: string`183184 URL of the image to fetch.185186 minLength: 1187188 - `BetaManagedAgentsFileImageSource object`189190 Image referenced by file ID.191192 - `type: "file"`193194 - `file_id: string`195196 ID of a previously uploaded file.197198 minLength: 1199200 - `BetaManagedAgentsDocumentBlock object`201202 Document content, either specified directly as base64 data, as text, or as a reference via a URL.203204 - `type: "document"`205206 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`207208 Union type for document source variants.209210 - `BetaManagedAgentsBase64DocumentSource object`211212 Base64-encoded document data.213214 - `type: "base64"`215216 - `data: string`217218 Base64-encoded document data.219220 minLength: 1221222 - `media_type: string`223224 MIME type of the document (e.g., "application/pdf").225226 minLength: 1227228 - `BetaManagedAgentsPlainTextDocumentSource object`229230 Plain text document content.231232 - `type: "text"`233234 - `data: string`235236 The plain text content.237238 minLength: 1239240 - `media_type: "text/plain"`241242 MIME type of the text content. Must be "text/plain".243244 - `BetaManagedAgentsURLDocumentSource object`245246 Document referenced by URL.247248 - `type: "url"`249250 - `url: string`251252 URL of the document to fetch.253254 minLength: 1255256 - `BetaManagedAgentsFileDocumentSource object`257258 Document referenced by file ID.259260 - `type: "file"`261262 - `file_id: string`263264 ID of a previously uploaded file.265266 minLength: 1267268 - `context: optional string or null`269270 Additional context about the document for the model.271272 - `title: optional string or null`273274 The title of the document.275276 - `BetaManagedAgentsRedactedBlock object`277278 Placeholder for content withheld by Anthropic model policy.279280 - `type: "redacted"`281282 - `BetaManagedAgentsUserInterruptEventParams object`283284 Parameters for sending an interrupt to pause the agent.285286 - `type: "user.interrupt"`287288 - `session_thread_id: optional string or null`289290 If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.291292 - `BetaManagedAgentsUserToolConfirmationEventParams object`293294 Parameters for confirming or denying a tool execution request.295296 - `type: "user.tool_confirmation"`297298 - `result: "allow" or "deny"`299300 UserToolConfirmationResult enum301302 - `"allow"`303304 - `"deny"`305306 - `tool_use_id: string`307308 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.309310 minLength: 1, maxLength: 128311312 - `deny_message: optional string or null`313314 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.315316 maxLength: 10000317318 - `BetaManagedAgentsUserCustomToolResultEventParams object`319320 Parameters for providing the result of a custom tool execution.321322 - `type: "user.custom_tool_result"`323324 - `custom_tool_use_id: string`325326 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.327328 minLength: 1, maxLength: 128329330 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`331332 The result content returned by the tool.333334 - `BetaManagedAgentsTextBlock object`335336 Regular text content.337338 - `BetaManagedAgentsImageBlock object`339340 Image content specified directly as base64 data or as a reference via a URL.341342 - `BetaManagedAgentsDocumentBlock object`343344 Document content, either specified directly as base64 data, as text, or as a reference via a URL.345346 - `BetaManagedAgentsSearchResultBlock object`347348 A block containing a web search result.349350 - `type: "search_result"`351352 - `citations: BetaManagedAgentsSearchResultCitations`353354 Citation settings for a search result.355356 - `enabled: boolean`357358 Whether citations are enabled for this search result.359360 - `content: array of BetaManagedAgentsSearchResultContent`361362 Array of text content blocks from the search result.363364 - `type: "text"`365366 - `text: string`367368 The text content.369370 minLength: 1371372 - `source: string`373374 The URL source of the search result.375376 minLength: 1377378 - `title: string`379380 The title of the search result.381382 minLength: 1383384 - `is_error: optional boolean or null`385386 Whether the tool execution resulted in an error.387388 - `BetaManagedAgentsUserDefineOutcomeEventParams object`389390 Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.391392 - `type: "user.define_outcome"`393394 - `description: string`395396 What the agent should produce. This is the task specification.397398 - `rubric: BetaManagedAgentsFileRubricParams or BetaManagedAgentsTextRubricParams`399400 Rubric for grading the quality of an outcome.401402 - `BetaManagedAgentsFileRubricParams object`403404 Rubric referenced by a file uploaded via the Files API.405406 - `type: "file"`407408 - `file_id: string`409410 ID of the rubric file.411412 - `BetaManagedAgentsTextRubricParams object`413414 Rubric content provided inline as text.415416 - `type: "text"`417418 - `content: string`419420 Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.421422 maxLength: 262144423424 - `max_iterations: optional number or null`425426 Eval→revision cycles before giving up. Default 3, max 20.427428 format: int32429430 - `BetaManagedAgentsUserToolResultEventParams object`431432 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.433434 - `type: "user.tool_result"`435436 - `tool_use_id: string`437438 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.439440 minLength: 1, maxLength: 128441442 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`443444 The result content returned by the tool.445446 - `BetaManagedAgentsTextBlock object`447448 Regular text content.449450 - `BetaManagedAgentsImageBlock object`451452 Image content specified directly as base64 data or as a reference via a URL.453454 - `BetaManagedAgentsDocumentBlock object`455456 Document content, either specified directly as base64 data, as text, or as a reference via a URL.457458 - `BetaManagedAgentsSearchResultBlock object`459460 A block containing a web search result.461462 - `is_error: optional boolean or null`463464 Whether the tool execution resulted in an error.465466 - `BetaManagedAgentsSystemMessageEventParams object`467468 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.469470 - `type: "system.message"`471472 - `content: array of BetaManagedAgentsSystemContentBlock`473474 System content blocks to append. Text-only.475476 - `type: "text"`477478 - `text: string`479480 The text content.481482 minLength: 1483484## Returns485486- `BetaManagedAgentsSendSessionEvents object`487488 Events that were successfully sent to the session.489490 - `data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 4 more`491492 Sent events493494 - `BetaManagedAgentsUserMessageEvent object`495496 A user message event in the session conversation.497498 - `type: "user.message"`499500 - `id: string`501502 Unique identifier for this event.503504 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`505506 Array of content blocks comprising the user message.507508 - `BetaManagedAgentsTextBlock object`509510 Regular text content.511512 - `type: "text"`513514 - `text: string`515516 The text content.517518 minLength: 1519520 - `BetaManagedAgentsImageBlock object`521522 Image content specified directly as base64 data or as a reference via a URL.523524 - `type: "image"`525526 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`527528 Union type for image source variants.529530 - `BetaManagedAgentsBase64ImageSource object`531532 Base64-encoded image data.533534 - `type: "base64"`535536 - `data: string`537538 Base64-encoded image data.539540 minLength: 1541542 - `media_type: string`543544 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").545546 minLength: 1547548 - `BetaManagedAgentsURLImageSource object`549550 Image referenced by URL.551552 - `type: "url"`553554 - `url: string`555556 URL of the image to fetch.557558 minLength: 1559560 - `BetaManagedAgentsFileImageSource object`561562 Image referenced by file ID.563564 - `type: "file"`565566 - `file_id: string`567568 ID of a previously uploaded file.569570 minLength: 1571572 - `BetaManagedAgentsDocumentBlock object`573574 Document content, either specified directly as base64 data, as text, or as a reference via a URL.575576 - `type: "document"`577578 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`579580 Union type for document source variants.581582 - `BetaManagedAgentsBase64DocumentSource object`583584 Base64-encoded document data.585586 - `type: "base64"`587588 - `data: string`589590 Base64-encoded document data.591592 minLength: 1593594 - `media_type: string`595596 MIME type of the document (e.g., "application/pdf").597598 minLength: 1599600 - `BetaManagedAgentsPlainTextDocumentSource object`601602 Plain text document content.603604 - `type: "text"`605606 - `data: string`607608 The plain text content.609610 minLength: 1611612 - `media_type: "text/plain"`613614 MIME type of the text content. Must be "text/plain".615616 - `BetaManagedAgentsURLDocumentSource object`617618 Document referenced by URL.619620 - `type: "url"`621622 - `url: string`623624 URL of the document to fetch.625626 minLength: 1627628 - `BetaManagedAgentsFileDocumentSource object`629630 Document referenced by file ID.631632 - `type: "file"`633634 - `file_id: string`635636 ID of a previously uploaded file.637638 minLength: 1639640 - `context: optional string or null`641642 Additional context about the document for the model.643644 - `title: optional string or null`645646 The title of the document.647648 - `BetaManagedAgentsRedactedBlock object`649650 Placeholder for content withheld by Anthropic model policy.651652 - `type: "redacted"`653654 - `processed_at: optional string or null`655656 A timestamp in RFC 3339 format657658 format: date-time659660 - `BetaManagedAgentsUserInterruptEvent object`661662 An interrupt event that pauses agent execution and returns control to the user.663664 - `type: "user.interrupt"`665666 - `id: string`667668 Unique identifier for this event.669670 - `processed_at: optional string or null`671672 A timestamp in RFC 3339 format673674 format: date-time675676 - `session_thread_id: optional string or null`677678 If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.679680 - `BetaManagedAgentsUserToolConfirmationEvent object`681682 A tool confirmation event that approves or denies a pending tool execution.683684 - `type: "user.tool_confirmation"`685686 - `id: string`687688 Unique identifier for this event.689690 - `result: "allow" or "deny"`691692 UserToolConfirmationResult enum693694 - `"allow"`695696 - `"deny"`697698 - `tool_use_id: string`699700 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.701702 - `deny_message: optional string or null`703704 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.705706 maxLength: 10000707708 - `processed_at: optional string or null`709710 A timestamp in RFC 3339 format711712 format: date-time713714 - `session_thread_id: optional string or null`715716 Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread.717718 - `BetaManagedAgentsUserCustomToolResultEvent object`719720 Event sent by the client providing the result of a custom tool execution.721722 - `type: "user.custom_tool_result"`723724 - `id: string`725726 Unique identifier for this event.727728 - `custom_tool_use_id: string`729730 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.731732 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`733734 The result content returned by the tool.735736 - `BetaManagedAgentsTextBlock object`737738 Regular text content.739740 - `BetaManagedAgentsImageBlock object`741742 Image content specified directly as base64 data or as a reference via a URL.743744 - `BetaManagedAgentsDocumentBlock object`745746 Document content, either specified directly as base64 data, as text, or as a reference via a URL.747748 - `BetaManagedAgentsSearchResultBlock object`749750 A block containing a web search result.751752 - `type: "search_result"`753754 - `citations: BetaManagedAgentsSearchResultCitations`755756 Citation settings for a search result.757758 - `enabled: boolean`759760 Whether citations are enabled for this search result.761762 - `content: array of BetaManagedAgentsSearchResultContent`763764 Array of text content blocks from the search result.765766 - `type: "text"`767768 - `text: string`769770 The text content.771772 minLength: 1773774 - `source: string`775776 The URL source of the search result.777778 minLength: 1779780 - `title: string`781782 The title of the search result.783784 minLength: 1785786 - `is_error: optional boolean or null`787788 Whether the tool execution resulted in an error.789790 - `processed_at: optional string or null`791792 A timestamp in RFC 3339 format793794 format: date-time795796 - `session_thread_id: optional string or null`797798 Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread.799800 - `BetaManagedAgentsUserDefineOutcomeEvent object`801802 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.803804 - `type: "user.define_outcome"`805806 - `id: string`807808 Unique identifier for this event.809810 - `description: string`811812 What the agent should produce. Copied from the input event.813814 - `max_iterations: number or null`815816 Evaluate-then-revise cycles before giving up. Default 3, max 20.817818 format: int32819820 - `outcome_id: string`821822 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.823824 - `processed_at: string`825826 A timestamp in RFC 3339 format827828 format: date-time829830 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`831832 Rubric for grading the quality of an outcome.833834 - `BetaManagedAgentsFileRubric object`835836 Rubric referenced by a file uploaded via the Files API.837838 - `type: "file"`839840 - `file_id: string`841842 ID of the rubric file.843844 - `BetaManagedAgentsTextRubric object`845846 Rubric content provided inline as text.847848 - `type: "text"`849850 - `content: string`851852 Rubric content. Plain text or markdown — the grader treats it as freeform text.853854 - `BetaManagedAgentsUserToolResultEvent object`855856 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.857858 - `type: "user.tool_result"`859860 - `id: string`861862 Unique identifier for this event.863864 - `tool_use_id: string`865866 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.867868 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`869870 The result content returned by the tool.871872 - `BetaManagedAgentsTextBlock object`873874 Regular text content.875876 - `BetaManagedAgentsImageBlock object`877878 Image content specified directly as base64 data or as a reference via a URL.879880 - `BetaManagedAgentsDocumentBlock object`881882 Document content, either specified directly as base64 data, as text, or as a reference via a URL.883884 - `BetaManagedAgentsSearchResultBlock object`885886 A block containing a web search result.887888 - `is_error: optional boolean or null`889890 Whether the tool execution resulted in an error.891892 - `processed_at: optional string or null`893894 A timestamp in RFC 3339 format895896 format: date-time897898 - `session_thread_id: optional string or null`899900 Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread.901902 - `BetaManagedAgentsSystemMessageEvent object`903904 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.905906 - `type: "system.message"`907908 - `id: string`909910 Unique identifier for this event.911912 - `content: array of BetaManagedAgentsSystemContentBlock`913914 System content blocks. Text-only.915916 - `type: "text"`917918 - `text: string`919920 The text content.921922 minLength: 1923924 - `processed_at: optional string or null`925926 A timestamp in RFC 3339 format927928 format: date-time929930## Example931932```bash933curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \934 -H 'Content-Type: application/json' \935 -H 'anthropic-version: 2023-06-01' \936 -H 'anthropic-beta: managed-agents-2026-04-01' \937 -H "X-Api-Key: $ANTHROPIC_API_KEY" \938 -d '{939 "events": [940 {941 "content": [942 {943 "text": "Where is my order #1234?",944 "type": "text"945 }946 ],947 "type": "user.message"948 }949 ]950 }'951```952953### Response (200)954955```json956{957 "data": [958 {959 "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy",960 "content": [961 {962 "text": "Where is my order #1234?",963 "type": "text"964 }965 ],966 "type": "user.message",967 "processed_at": "2026-03-15T10:00:00Z"968 }969 ]970}971```972