Send Events

post /v1/sessions/{session_id}/events

Send Events

Path Parameters

• session_id: string

Header Parameters

• "anthropic-beta": optional array of AnthropicBeta

  Optional header to specify the beta version(s) you want to use.

  • string

  • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 more

    • "message-batches-2024-09-24"

    • "prompt-caching-2024-07-31"

    • "computer-use-2024-10-22"

    • "computer-use-2025-01-24"

    • "pdfs-2024-09-25"

    • "token-counting-2024-11-01"

    • "token-efficient-tools-2025-02-19"

    • "output-128k-2025-02-19"

    • "files-api-2025-04-14"

    • "mcp-client-2025-04-04"

    • "mcp-client-2025-11-20"

    • "dev-full-thinking-2025-05-14"

    • "interleaved-thinking-2025-05-14"

    • "code-execution-2025-05-22"

    • "extended-cache-ttl-2025-04-11"

    • "context-1m-2025-08-07"

    • "context-management-2025-06-27"

    • "model-context-window-exceeded-2025-08-26"

    • "skills-2025-10-02"

    • "fast-mode-2026-02-01"

    • "output-300k-2026-03-24"

    • "user-profiles-2026-03-24"

    • "advisor-tool-2026-03-01"

    • "managed-agents-2026-04-01"

    • "cache-diagnosis-2026-04-07"

Body Parameters

• events: array of BetaManagedAgentsEventParams

  Events to send to the session.

  • BetaManagedAgentsUserMessageEventParams object { content, type }

    Parameters for sending a user message to the session.

    • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

      Array of content blocks for the user message.

      • BetaManagedAgentsTextBlock object { text, type }

        Regular text content.

        • text: string

          The text content.

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        Image content specified directly as base64 data or as a reference via a URL.

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          Union type for image source variants.

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            Base64-encoded image data.

            • data: string

              Base64-encoded image data.

            • media_type: string

              MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

            • type: "base64"

              • "base64"

          • BetaManagedAgentsURLImageSource object { type, url }

            Image referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the image to fetch.

          • BetaManagedAgentsFileImageSource object { file_id, type }

            Image referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          Union type for document source variants.

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            Base64-encoded document data.

            • data: string

              Base64-encoded document data.

            • media_type: string

              MIME type of the document (e.g., "application/pdf").

            • type: "base64"

              • "base64"

          • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

            Plain text document content.

            • data: string

              The plain text content.

            • media_type: "text/plain"

              MIME type of the text content. Must be "text/plain".

              • "text/plain"

            • type: "text"

              • "text"

          • BetaManagedAgentsURLDocumentSource object { type, url }

            Document referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the document to fetch.

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            Document referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          Additional context about the document for the model.

        • title: optional string

          The title of the document.

    • type: "user.message"

      • "user.message"

  • BetaManagedAgentsUserInterruptEventParams object { type, session_thread_id }

    Parameters for sending an interrupt to pause the agent.

    • type: "user.interrupt"

      • "user.interrupt"

    • session_thread_id: optional string

      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.

  • BetaManagedAgentsUserToolConfirmationEventParams object { result, tool_use_id, type, deny_message }

    Parameters for confirming or denying a tool execution request.

    • result: "allow" or "deny"

      UserToolConfirmationResult enum

      • "allow"

      • "deny"

    • tool_use_id: string

      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 stop_reason.event_ids field.

    • type: "user.tool_confirmation"

      • "user.tool_confirmation"

    • deny_message: optional string

      Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

  • BetaManagedAgentsUserCustomToolResultEventParams object { custom_tool_use_id, type, content, is_error }

    Parameters for providing the result of a custom tool execution.

    • custom_tool_use_id: string

      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 stop_reason.event_ids field.

    • type: "user.custom_tool_result"

      • "user.custom_tool_result"

    • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

      The result content returned by the tool.

      • BetaManagedAgentsTextBlock object { text, type }

        Regular text content.

      • BetaManagedAgentsImageBlock object { source, type }

        Image content specified directly as base64 data or as a reference via a URL.

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

        A block containing a web search result.

        • citations: BetaManagedAgentsSearchResultCitations

          Citation settings for a search result.

          • enabled: boolean

            Whether citations are enabled for this search result.

        • content: array of BetaManagedAgentsSearchResultContent

          Array of text content blocks from the search result.

          • text: string

            The text content.

          • type: "text"

            • "text"

        • source: string

          The URL source of the search result.

        • title: string

          The title of the search result.

        • type: "search_result"

          • "search_result"

    • is_error: optional boolean

      Whether the tool execution resulted in an error.

  • BetaManagedAgentsUserDefineOutcomeEventParams object { description, rubric, type, max_iterations }

    Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.

    • description: string

      What the agent should produce. This is the task specification.

    • rubric: BetaManagedAgentsFileRubricParams or BetaManagedAgentsTextRubricParams

      Rubric for grading the quality of an outcome.

      • BetaManagedAgentsFileRubricParams object { file_id, type }

        Rubric referenced by a file uploaded via the Files API.

        • file_id: string

          ID of the rubric file.

        • type: "file"

          • "file"

      • BetaManagedAgentsTextRubricParams object { content, type }

        Rubric content provided inline as text.

        • content: string

          Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.

        • type: "text"

          • "text"

    • type: "user.define_outcome"

      • "user.define_outcome"

    • max_iterations: optional number

      Eval→revision cycles before giving up. Default 3, max 20.

  • BetaManagedAgentsUserToolResultEventParams object { tool_use_id, type, content, is_error }

    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.

    • tool_use_id: string

      The id of the agent.tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.

    • type: "user.tool_result"

      • "user.tool_result"

    • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

      The result content returned by the tool.

      • BetaManagedAgentsTextBlock object { text, type }

        Regular text content.

      • BetaManagedAgentsImageBlock object { source, type }

        Image content specified directly as base64 data or as a reference via a URL.

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

        A block containing a web search result.

    • is_error: optional boolean

      Whether the tool execution resulted in an error.

Returns

• BetaManagedAgentsSendSessionEvents object { data }

  Events that were successfully sent to the session.

  • data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 3 more

    Sent events

    • BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }

      A user message event in the session conversation.

      • id: string

        Unique identifier for this event.

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Array of content blocks comprising the user message.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

          • text: string

            The text content.

          • type: "text"

            • "text"

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

          • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

            Union type for image source variants.

            • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

              Base64-encoded image data.

              • data: string

                Base64-encoded image data.

              • media_type: string

                MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

              • type: "base64"

                • "base64"

            • BetaManagedAgentsURLImageSource object { type, url }

              Image referenced by URL.

              • type: "url"

                • "url"

              • url: string

                URL of the image to fetch.

            • BetaManagedAgentsFileImageSource object { file_id, type }

              Image referenced by file ID.

              • file_id: string

                ID of a previously uploaded file.

              • type: "file"

                • "file"

          • type: "image"

            • "image"

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

            Union type for document source variants.

            • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

              Base64-encoded document data.

              • data: string

                Base64-encoded document data.

              • media_type: string

                MIME type of the document (e.g., "application/pdf").

              • type: "base64"

                • "base64"

            • BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }

              Plain text document content.

              • data: string

                The plain text content.

              • media_type: "text/plain"

                MIME type of the text content. Must be "text/plain".

                • "text/plain"

              • type: "text"

                • "text"

            • BetaManagedAgentsURLDocumentSource object { type, url }

              Document referenced by URL.

              • type: "url"

                • "url"

              • url: string

                URL of the document to fetch.

            • BetaManagedAgentsFileDocumentSource object { file_id, type }

              Document referenced by file ID.

              • file_id: string

                ID of a previously uploaded file.

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • context: optional string

            Additional context about the document for the model.

          • title: optional string

            The title of the document.

      • type: "user.message"

        • "user.message"

      • processed_at: optional string

        A timestamp in RFC 3339 format

    • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

      An interrupt event that pauses agent execution and returns control to the user.

      • id: string

        Unique identifier for this event.

      • type: "user.interrupt"

        • "user.interrupt"

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        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.

    • BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }

      A tool confirmation event that approves or denies a pending tool execution.

      • id: string

        Unique identifier for this event.

      • result: "allow" or "deny"

        UserToolConfirmationResult enum

        • "allow"

        • "deny"

      • tool_use_id: string

        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 stop_reason.event_ids field.

      • type: "user.tool_confirmation"

        • "user.tool_confirmation"

      • deny_message: optional string

        Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the session_thread_id on the agent.tool_use or agent.mcp_tool_use event that prompted the approval.

    • BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }

      Event sent by the client providing the result of a custom tool execution.

      • id: string

        Unique identifier for this event.

      • custom_tool_use_id: string

        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 stop_reason.event_ids field.

      • type: "user.custom_tool_result"

        • "user.custom_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

          • citations: BetaManagedAgentsSearchResultCitations

            Citation settings for a search result.

            • enabled: boolean

              Whether citations are enabled for this search result.

          • content: array of BetaManagedAgentsSearchResultContent

            Array of text content blocks from the search result.

            • text: string

              The text content.

            • type: "text"

              • "text"

          • source: string

            The URL source of the search result.

          • title: string

            The title of the search result.

          • type: "search_result"

            • "search_result"

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        Routes this result to a subagent thread. Copy from the agent.custom_tool_use event's session_thread_id.

    • BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }

      Echo of a user.define_outcome input event. Carries the server-generated outcome_id that subsequent span.outcome_evaluation_* events reference.

      • id: string

        Unique identifier for this event.

      • description: string

        What the agent should produce. Copied from the input event.

      • max_iterations: number

        Evaluate-then-revise cycles before giving up. Default 3, max 20.

      • outcome_id: string

        Server-generated outc_ ID for this outcome. Referenced by span.outcome_evaluation_* events and the session's outcome_evaluations list.

      • processed_at: string

        A timestamp in RFC 3339 format

      • rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric

        Rubric for grading the quality of an outcome.

        • BetaManagedAgentsFileRubric object { file_id, type }

          Rubric referenced by a file uploaded via the Files API.

          • file_id: string

            ID of the rubric file.

          • type: "file"

            • "file"

        • BetaManagedAgentsTextRubric object { content, type }

          Rubric content provided inline as text.

          • content: string

            Rubric content. Plain text or markdown — the grader treats it as freeform text.

          • type: "text"

            • "text"

      • type: "user.define_outcome"

        • "user.define_outcome"

    • BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }

      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.

      • id: string

        Unique identifier for this event.

      • tool_use_id: string

        The id of the agent.tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.

      • type: "user.tool_result"

        • "user.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        Routes this result to a subagent thread. Copy from the agent.tool_use event's session_thread_id.

Example

curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "events": [
            {
              "content": [
                {
                  "text": "Where is my order #1234?",
                  "type": "text"
                }
              ],
              "type": "user.message"
            }
          ]
        }'

Response

{
  "data": [
    {
      "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy",
      "content": [
        {
          "text": "Where is my order #1234?",
          "type": "text"
        }
      ],
      "type": "user.message",
      "processed_at": "2026-03-15T10:00:00Z"
    }
  ]
}