> ## Documentation Index
> Fetch the complete documentation index at: https://docs.envole.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Session Thread Message

> Adds a message to a session thread and streams events back using Server-Sent Events.

Send a new message to a session thread and receive updates as it is processed.

Responses are returned as Server-Sent Events that stream message processing updates. See the [Streaming](/api-reference/streaming/index) section for event types and payload formats.


## OpenAPI

````yaml POST /api/assistants/threads/{threadId}/messages
openapi: 3.1.0
info:
  title: Session Thread API
  description: API for managing session threads.
  license:
    name: MIT
    identifier: ''
  version: 1.0.0
servers:
  - url: https://agent-service-511985928315.us-east4.run.app
security:
  - bearerAuth: []
    XEnvoleUserId: []
paths:
  /api/assistants/threads/{threadId}/messages:
    post:
      summary: Add a message to a session thread
      description: >-
        Adds a message to a session thread and streams events back using
        Server-Sent Events.
      parameters:
        - name: threadId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddSessionThreadMessageDto'
            example:
              content:
                - type: text
                  text: Hi what can you do for me
      responses:
        '200':
          description: SSE stream of events from the agent.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/SseEvent'
              examples:
                sample:
                  summary: Sample SSE stream
                  value:
                    type: AGENT_RESPONSE_CHUNK
                    eventId: ''
                    threadId: ''
                    requestId: ''
                    eventMessage:
                      agent: null
                      content: Hel
                      collaborationId: null
                      activeAssistantCollaborationRequired: null
                      toolExecutionApprovalRequest: null
                      timestamp: '2025-08-12T00:00:00'
        '400':
          description: Bad request.
        '404':
          description: Agent or thread not found.
        '500':
          description: Internal server error.
components:
  schemas:
    AddSessionThreadMessageDto:
      type: object
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/ThreadMessageContentDto'
      required:
        - content
      example:
        content:
          - type: text
            text: Hi what can you do for me
          - type: document
            fileId: c6376b28-4f6c-429c-b4ae-917f5aaf2987
          - type: image
            imageId: 0d5d58eb-affd-4eb3-b4ec-fb6d61911e17
          - type: tool_approval_result
            toolApprovalResult:
              - toolId: tool_123
                toolName: Calendar
                toolProvider: Google
                toolCategory: SCHEDULING
                toolExecutionId: exec_123
                toolExecutionBatchId: batch_456
                toolMemoryId: mem_789
                approvalResult: APPROVED
    SseEvent:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/SseEventType'
        eventId:
          type: string
        threadId:
          type: string
        requestId:
          type: string
        eventMessage:
          $ref: '#/components/schemas/SseEventMessage'
      required:
        - type
        - eventId
        - threadId
        - requestId
        - eventMessage
    ThreadMessageContentDto:
      oneOf:
        - $ref: '#/components/schemas/TextContentDto'
          title: Text
        - $ref: '#/components/schemas/ToolApprovalContentDto'
          title: Tool Approval Result
        - $ref: '#/components/schemas/FileContentDto'
          title: File
        - $ref: '#/components/schemas/ImageFileContentDto'
          title: Image
    SseEventType:
      type: string
      enum:
        - CONNECTION_ESTABLISHED
        - MESSAGE_RECEIVED
        - AGENT_RESPONSE_CHUNK
        - AGENT_RESPONSE_COMPLETE
        - TOOL_EXECUTION_APPROVAL_REQUEST
        - TOOL_EXECUTION_APPROVAL_RESPONSE
        - NOTIFICATION_TOOL_EXECUTION_INITIATED
        - NOTIFICATION_TOOL_EXECUTION_IN_PROGRESS
        - NOTIFICATION_TOOL_EXECUTION_APPROVAL_REQUIRED
        - NOTIFICATION_TOOL_EXECUTION_APPROVAL_ACCEPTED
        - NOTIFICATION_TOOL_EXECUTION_APPROVAL_DENIED
        - NOTIFICATION_TOOL_EXECUTION_APPROVAL_ABORTED
        - NOTIFICATION_AGENT_THINKING_STARTED
        - NOTIFICATION_AGENT_THINKING_COMPLETE
        - NOTIFICATION_KNOWLEDGE_RETRIEVAL_INITIATED
        - NOTIFICATION_KNOWLEDGE_RETRIEVAL_IN_PROGRESS
        - NOTIFICATION_KNOWLEDGE_RETRIEVAL_COMPLETED
        - NOTIFICATION_KNOWLEDGE_RETRIEVAL_FAILED
        - NOTIFICATION_KNOWLEDGE_RETRIEVAL_DUPLICATED_CACHED
        - NOTIFICATION_REQUEST_ORCHESTRATION_SIMPLE
        - NOTIFICATION_REQUEST_ORCHESTRATION_COMPLEX
        - NOTIFICATION_REQUEST_ORCHESTRATION_CAPABILITIES
        - NOTIFICATION_REQUEST_ORCHESTRATION_KNOWLEDGE_BASE
        - NOTIFICATION_REQUEST_ORCHESTRATION_TOOL_USAGE
        - NOTIFICATION_REQUEST_ORCHESTRATION_COLLABORATION
        - NOTIFICATION_PLAN_ORCHESTRATION_COMPLEX_INITIATED
        - NOTIFICATION_PLAN_ORCHESTRATION_COMPLEX_IN_PROGRESS
        - NOTIFICATION_PLAN_ORCHESTRATION_COMPLEX_COMPLETED
        - NOTIFICATION_PLAN_ORCHESTRATION_COMPLEX_REVIEW_INITIATED
        - NOTIFICATION_PLAN_ORCHESTRATION_COMPLEX_REVIEW_IN_PROGRESS
        - NOTIFICATION_PLAN_ORCHESTRATION_COMPLEX_REVIEW_COMPLETED
        - NOTIFICATION_PLAN_ORCHESTRATION_KNOWLEDGE_BASE_INITIATED
        - NOTIFICATION_PLAN_ORCHESTRATION_KNOWLEDGE_BASE_IN_PROGRESS
        - NOTIFICATION_PLAN_ORCHESTRATION_KNOWLEDGE_BASE_COMPLETED
        - NOTIFICATION_PLAN_ORCHESTRATION_KNOWLEDGE_RETRIEVAL_INITIATED
        - NOTIFICATION_PLAN_ORCHESTRATION_TOOL_USAGE_INITIATED
        - NOTIFICATION_PLAN_ORCHESTRATION_TOOL_USAGE_IN_PROGRESS
        - NOTIFICATION_PLAN_ORCHESTRATION_TOOL_USAGE_COMPLETED
        - NOTIFICATION_PLAN_ORCHESTRATION_REFLECTION_INITIATED
        - NOTIFICATION_PLAN_ORCHESTRATION_REFLECTION_ABORTED
        - NOTIFICATION_PLAN_ORCHESTRATION_REFLECTION_FAILED
        - NOTIFICATION_PLAN_ORCHESTRATION_REFLECTION_COMPLETED
        - NOTIFICATION_PLAN_ORCHESTRATION_COLLABORATION_INITIATED
        - NOTIFICATION_PLAN_ORCHESTRATION_COLLABORATION_IN_PROGRESS
        - NOTIFICATION_PLAN_ORCHESTRATION_COLLABORATION_COMPLETED
        - NOTIFICATION_MULTI_ASSISTANT_COLLABORATION_STARTED
        - >-
          NOTIFICATION_MULTI_ASSISTANT_COLLABORATION_ASSISTANT_RESPONSE_IN_PROGRESS
        - >-
          NOTIFICATION_MULTI_ASSISTANT_COLLABORATION_ASSISTANT_RESPONSE_COMPLETED
        - NOTIFICATION_MULTI_ASSISTANT_COLLABORATION_UNIFIED_RESPONSE_STARTED
        - >-
          NOTIFICATION_MULTI_ASSISTANT_COLLABORATION_NO_UNIFIED_RESPONSE_REQUIRED
        - NOTIFICATION_MULTI_ASSISTANT_COLLABORATION_COMPLETED
        - NOTIFICATION_MULTI_ASSISTANT_COLLABORATION_FAILED
        - NOTIFICATION_CONTEXT_MEMORIES_RETRIEVAL_FAILED
        - ERROR
    SseEventMessage:
      type: object
      properties:
        agent:
          $ref: '#/components/schemas/Agent'
        content:
          type: string
        collaborationId:
          type: string
          nullable: true
        activeAssistantCollaborationRequired:
          type: boolean
          nullable: true
        toolExecutionApprovalRequest:
          type: array
          items:
            $ref: '#/components/schemas/UserToolExecutionApprovalRequest'
          nullable: true
        timestamp:
          type: string
          format: date-time
      required:
        - content
        - timestamp
    TextContentDto:
      type: object
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
          description: Text content to send.
      required:
        - type
        - text
    ToolApprovalContentDto:
      type: object
      properties:
        type:
          type: string
          enum:
            - tool_approval_result
        toolApprovalResult:
          type: array
          items:
            $ref: '#/components/schemas/UserToolExecutionApprovalResponse'
      required:
        - type
        - toolApprovalResult
    FileContentDto:
      type: object
      properties:
        type:
          type: string
          enum:
            - document
        fileId:
          type: string
          description: File identifier.
      required:
        - type
        - fileId
    ImageFileContentDto:
      type: object
      properties:
        type:
          type: string
          enum:
            - image
        imageId:
          type: string
          description: Image file identifier.
      required:
        - type
        - imageId
    Agent:
      type: object
      properties:
        name:
          type: string
        id:
          type: string
        buildId:
          type: string
        buildType:
          type: string
        handle:
          type: string
      required:
        - name
        - id
        - buildType
        - handle
    UserToolExecutionApprovalRequest:
      type: object
      properties:
        toolId:
          type: string
        toolName:
          type: string
        toolProvider:
          type: string
        toolCategory:
          type: string
        toolExecutionId:
          type: string
        toolExecutionBatchId:
          type: string
        toolMemoryId:
          type: string
        toolArguments:
          type: object
          additionalProperties:
            type: string
      required:
        - toolId
        - toolName
        - toolProvider
        - toolCategory
        - toolExecutionId
        - toolExecutionBatchId
        - toolMemoryId
        - toolArguments
    UserToolExecutionApprovalResponse:
      type: object
      properties:
        toolId:
          type: string
        toolName:
          type: string
        toolProvider:
          type: string
        toolCategory:
          type: string
        toolExecutionId:
          type: string
        toolExecutionBatchId:
          type: string
        toolMemoryId:
          type: string
        approvalResult:
          $ref: '#/components/schemas/ToolExecutionHumanApprovalStatus'
      required:
        - toolId
        - toolName
        - toolProvider
        - toolCategory
        - toolExecutionId
        - toolExecutionBatchId
        - toolMemoryId
        - approvalResult
    ToolExecutionHumanApprovalStatus:
      type: string
      enum:
        - PENDING_HUMAN_APPROVAL
        - APPROVED
        - DENIED
        - ABORTED_WITH_FEEDBACK
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    XEnvoleUserId:
      type: apiKey
      in: header
      name: X-Envole-User-Id
      description: External user identifier; not necessarily registered with Envole

````