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

# Send Message

> Send a message to the agent and stream the response.

This endpoint streams Server-Sent Events (SSE) back to the client as
the agent processes the message through its workflow.

## SSE Event Types

**Core Events:**
- `intent`: Intent classification result (emitted first)
    - `{intent, confidence, category, reasoning, context_scope}`
- `thinking`: Agent is analyzing/planning
    - `{step, message}`
- `tool_call`: Agent is calling a tool
    - `{tool_name, tool_call_id, inputs}`
- `tool_result`: Tool execution completed
    - `{tool_name, tool_call_id, success, output, latency_ms}`
- `token`: Response token (streaming)
    - `{content}`
- `message`: Final response content
    - `{content, message_id, is_final}`
- `session_name`: Auto-generated session name (first message only)
    - `{session_name}`
- `done`: Processing complete
    - `{latency_ms, tool_calls_made, message_id, retriever_summary, data_accessed_via_retriever}`
- `error`: Error occurred
    - `{message, recoverable}`

**Retriever Events (IMPORTANT - Primary Data Pathway):**
- `retriever_execution`: Retriever was used for data access
    - `{tool_name, execution_id, retriever_id, is_adhoc, documents_returned, latency_ms, message}`
    - Emitted whenever data is accessed via retriever (saved or ad-hoc)
- `pipeline_config`: Ad-hoc retriever configuration
    - `{tool_name, config, message}`
    - Contains the exact pipeline config users can save as a named retriever

**Retriever Summary in `done` Event:**
```json
{
  "retriever_summary": {
    "used_retrievers": true,
    "retriever_count": 2,
    "saved_retrievers": 1,
    "adhoc_retrievers": 1,
    "total_documents": 25,
    "executions": [...]
  },
  "data_accessed_via_retriever": true
}
```

Args:
    request: FastAPI request with tenant context
    session_id: Session identifier
    payload: Message request

Returns:
    StreamingResponse with SSE events

Raises:
    NotFoundError: If session not found

Example:
    ```bash
    curl -N -X POST http://localhost:8000/v1/agents/sessions/ses_abc123/messages \
      -H "Authorization: Bearer {api_key}" \
      -H "X-Namespace: {namespace_id}" \
      -H "Content-Type: application/json" \
      -d '{
        "content": "Find videos about machine learning",
        "stream": true
      }'

    # SSE Output:
    event: intent
    data: {"intent": "retriever_search", "confidence": 0.92, "category": "retriever"}

    event: thinking
    data: {"step": "processing", "message": "Analyzing your request..."}

    event: tool_call
    data: {"tool_name": "execute_retriever", "tool_call_id": "run_abc", "inputs": {...}}

    event: tool_result
    data: {"tool_name": "execute_retriever", "success": true, "output": {...}}

    event: retriever_execution
    data: {"tool_name": "execute_retriever", "is_adhoc": false, "documents_returned": 5}

    event: message
    data: {"content": "I found 5 videos about machine learning...", "is_final": true}

    event: done
    data: {"latency_ms": 1250.5, "data_accessed_via_retriever": true, "retriever_summary": {...}}
    ```



## OpenAPI

````yaml post /v1/agents/sessions/{session_id}/messages
openapi: 3.1.0
info:
  title: Mixpeek API
  description: >-
    This is the Mixpeek API, providing access to various endpoints for data
    processing and retrieval.
  termsOfService: https://mixpeek.com/terms
  contact:
    name: Mixpeek Support
    url: https://mixpeek.com/contact
    email: info@mixpeek.com
  version: '0.82'
servers:
  - url: https://api.mixpeek.com
    description: Production
security: []
paths:
  /v1/agents/sessions/{session_id}/messages:
    post:
      tags:
        - Agent Sessions
      summary: Send Message
      description: |-
        Send a message to the agent and stream the response.

        This endpoint streams Server-Sent Events (SSE) back to the client as
        the agent processes the message through its workflow.

        ## SSE Event Types

        **Core Events:**
        - `intent`: Intent classification result (emitted first)
            - `{intent, confidence, category, reasoning, context_scope}`
        - `thinking`: Agent is analyzing/planning
            - `{step, message}`
        - `tool_call`: Agent is calling a tool
            - `{tool_name, tool_call_id, inputs}`
        - `tool_result`: Tool execution completed
            - `{tool_name, tool_call_id, success, output, latency_ms}`
        - `token`: Response token (streaming)
            - `{content}`
        - `message`: Final response content
            - `{content, message_id, is_final}`
        - `session_name`: Auto-generated session name (first message only)
            - `{session_name}`
        - `done`: Processing complete
            - `{latency_ms, tool_calls_made, message_id, retriever_summary, data_accessed_via_retriever}`
        - `error`: Error occurred
            - `{message, recoverable}`

        **Retriever Events (IMPORTANT - Primary Data Pathway):**
        - `retriever_execution`: Retriever was used for data access
            - `{tool_name, execution_id, retriever_id, is_adhoc, documents_returned, latency_ms, message}`
            - Emitted whenever data is accessed via retriever (saved or ad-hoc)
        - `pipeline_config`: Ad-hoc retriever configuration
            - `{tool_name, config, message}`
            - Contains the exact pipeline config users can save as a named retriever

        **Retriever Summary in `done` Event:**
        ```json
        {
          "retriever_summary": {
            "used_retrievers": true,
            "retriever_count": 2,
            "saved_retrievers": 1,
            "adhoc_retrievers": 1,
            "total_documents": 25,
            "executions": [...]
          },
          "data_accessed_via_retriever": true
        }
        ```

        Args:
            request: FastAPI request with tenant context
            session_id: Session identifier
            payload: Message request

        Returns:
            StreamingResponse with SSE events

        Raises:
            NotFoundError: If session not found

        Example:
            ```bash
            curl -N -X POST http://localhost:8000/v1/agents/sessions/ses_abc123/messages \
              -H "Authorization: Bearer {api_key}" \
              -H "X-Namespace: {namespace_id}" \
              -H "Content-Type: application/json" \
              -d '{
                "content": "Find videos about machine learning",
                "stream": true
              }'

            # SSE Output:
            event: intent
            data: {"intent": "retriever_search", "confidence": 0.92, "category": "retriever"}

            event: thinking
            data: {"step": "processing", "message": "Analyzing your request..."}

            event: tool_call
            data: {"tool_name": "execute_retriever", "tool_call_id": "run_abc", "inputs": {...}}

            event: tool_result
            data: {"tool_name": "execute_retriever", "success": true, "output": {...}}

            event: retriever_execution
            data: {"tool_name": "execute_retriever", "is_adhoc": false, "documents_returned": 5}

            event: message
            data: {"content": "I found 5 videos about machine learning...", "is_final": true}

            event: done
            data: {"latency_ms": 1250.5, "data_accessed_via_retriever": true, "retriever_summary": {...}}
            ```
      operationId: send_message_v1_agents_sessions__session_id__messages_post
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
            description: Session ID
            title: Session Id
          description: Session ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SendMessageRequest:
      properties:
        content:
          type: string
          minLength: 1
          title: Content
          description: Message text content (REQUIRED)
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: Message metadata (OPTIONAL)
        stream:
          type: boolean
          title: Stream
          description: 'Stream response as SSE (default: True)'
          default: true
      type: object
      required:
        - content
      title: SendMessageRequest
      description: |-
        Request payload for sending a message to the agent.

        Attributes:
            content: Message text content
            metadata: Optional message metadata
            stream: Whether to stream response as SSE (default: True)

        Note:
            When stream=True, the response will be Server-Sent Events (SSE).
            When stream=False, the response will be a MessageResponse object.

        Example:
            ```python
            # Streaming request (SSE)
            request = SendMessageRequest(
                content="Find videos about machine learning",
                stream=True
            )

            # Non-streaming request
            request = SendMessageRequest(
                content="Find videos about machine learning",
                stream=False
            )
            ```
      examples:
        - content: Find videos about machine learning
          metadata:
            source: web_app
          stream: true
    ErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Always false for error responses
          default: false
        status:
          type: integer
          title: Status
          description: HTTP status code for this error
        error:
          $ref: '#/components/schemas/ErrorDetail'
          description: Error details payload
      type: object
      required:
        - status
        - error
      title: ErrorResponse
      description: Error response model.
      examples:
        - error:
            details:
              id: ns_123
              resource: namespace
            message: Namespace not found
            type: NotFoundError
          status: 404
          success: false
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ErrorDetail:
      properties:
        message:
          type: string
          title: Message
          description: Human-readable error message
        type:
          type: string
          title: Type
          description: Stable error type identifier (machine-readable)
        code:
          anyOf:
            - type: string
            - type: 'null'
          title: Code
          description: >-
            Fine-grained error code for programmatic handling (e.g.,
            namespace_name_taken, feature_extractor_not_found). Present only
            when consumers may need to branch on a specific error condition.
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Details
          description: >-
            Optional structured details to help debugging (validation errors,
            IDs, etc.)
      type: object
      required:
        - message
        - type
      title: ErrorDetail
      description: Error detail model.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````